# Development
Contributing, building from source, and development guidelines.
## 🤝 Contributing
We welcome contributions! Here's how to get started.
### Ways to Contribute
- 🐛 **Report bugs** - [Open an issue](https://github.com/ndave92/claude-code-status-line/issues)
- ✨ **Suggest features** - [Start a discussion](https://github.com/ndave92/claude-code-status-line/discussions)
- 📝 **Improve documentation** - Submit a PR for wiki or README updates
- 🎨 **Share themes** - Post your color schemes in discussions
- 💻 **Submit code** - Fix bugs or implement features
### Before Contributing
1. Check [existing issues](https://github.com/ndave92/claude-code-status-line/issues)
2. For major changes, open an issue or discussion first
3. Follow the code style (enforced by `rustfmt` and `clippy`)
---
## 🛠️ Development Setup
### Prerequisites
- **Rust** (stable toolchain)
macOS / Linux:
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
Windows: Download and run [rustup-init.exe](https://rustup.rs/)
- **Git**
- **Claude Code** (for testing)
### Clone and Build
```bash
# Clone the repository
git clone https://github.com/ndave92/claude-code-status-line.git
cd claude-code-status-line
# Build debug version
cargo build
# Build release version
cargo build --release
# Run tests
cargo test
# Check formatting
cargo fmt --all -- --check
# Run linter
cargo clippy --all-targets --all-features -- -D warnings
```
### Development Workflow
```bash
# Create a feature branch
git checkout -b feature/my-feature
# Make changes and test
cargo build
cargo test
# Format code
cargo fmt --all
# Check for issues
cargo clippy --all-targets --all-features
# Run validation script
bash scripts/validate.sh
# Commit and push
git add .
git commit -m "Description of changes"
git push origin feature/my-feature
```
---
## 🏗️ Project Structure
```
claude-code-status-line/
├── src/
│ ├── main.rs # Entry point
│ ├── lib.rs # Library interface
│ ├── config.rs # Configuration loading
│ ├── colors.rs # Color definitions
│ ├── statusline.rs # Main statusline logic
│ ├── render.rs # Rendering functions
│ ├── context.rs # Context usage handling
│ ├── quota.rs # Quota API integration
│ ├── git.rs # Git information
│ ├── types.rs # Common types
│ └── utils.rs # Utility functions
├── docs/
│ └── wiki/ # Wiki content
├── scripts/
│ ├── validate.sh # Validation script
│ └── quick-check.sh # Quick checks
├── .claude/
│ └── commands/ # Claude Code commands
│ ├── install-statusline.md
│ └── update-statusline.md
├── .github/
│ └── workflows/ # CI/CD workflows
│ ├── ci.yml
│ ├── release.yml
│ └── publish-crates.yml
├── Cargo.toml # Dependencies and metadata
├── settings.json # Example config
├── colors.json # Example colors
└── README.md
```
### Module Overview
- **main.rs** - Reads JSON input from stdin, parses it, and renders the status line
- **config.rs** - Loads and validates `settings.json` and `colors.json`
- **statusline.rs** - Orchestrates section rendering and layout
- **render.rs** - ANSI escape code generation for colors and styling
- **quota.rs** - Fetches quota information from Claude API
- **git.rs** - Detects git branch and status
- **context.rs** - Calculates context usage percentages
- **utils.rs** - Text truncation, width calculation, etc.
---
## 🧪 Testing
### Run Tests
```bash
# All tests
cargo test
# Specific test
cargo test test_name
# With output
cargo test -- --nocapture
# Documentation tests
cargo test --doc
```
### Manual Testing
Test with sample input:
```bash
# Build
cargo build
# Test with sample data
echo '{"workspace":{"current_dir":"/Users/test/project"},"model":{"display_name":"Sonnet 4.5"},"context_window":{"context_window_size":200000,"current_usage":{"input_tokens":15000}}}' | ./target/debug/claude-code-status-line
```
### Test with Claude Code
1. Build the binary
2. Update your `~/.claude/settings.json` to point to the debug binary:
```json
{
"statusLine": {
"type": "command",
"command": "/path/to/claude-code-status-line/target/debug/claude-code-status-line",
"padding": 0
}
}
```
3. Restart Claude Code
4. Make changes and rebuild (`cargo build`)
5. Restart Claude Code to see changes
---
## 📋 Code Style
### Formatting
Use `rustfmt` for consistent formatting:
```bash
# Format all code
cargo fmt --all
# Check without modifying
cargo fmt --all -- --check
```
### Linting
Use `clippy` for best practices:
```bash
# Run clippy
cargo clippy --all-targets --all-features
# Deny warnings
cargo clippy --all-targets --all-features -- -D warnings
```
### Style Guidelines
- Use descriptive variable names
- Add comments for complex logic
- Keep functions focused and small
- Use Rust idioms (Result, Option, iterators)
- Prefer immutability when possible
- Handle errors gracefully
---
## 🔄 Validation Script
Run the full validation suite before committing:
**macOS / Linux:**
```bash
bash scripts/validate.sh
```
**Windows:**
Using Git Bash (recommended):
```bash
bash scripts/validate.sh
```
Or run manually in PowerShell:
```powershell
cargo fmt --all
cargo clippy --all-targets --all-features -- -D warnings
cargo test
cargo build --release
```
This runs:
1. Code formatting (with auto-fix)
2. Clippy checks
3. All tests
4. Release build
---
## 📦 Release Process
### Version Bumping
1. Update version in `Cargo.toml`
2. Update version in `Cargo.lock`:
```bash
cargo build
```
3. Commit changes:
```bash
git add Cargo.toml Cargo.lock
git commit -m "Bump version to X.Y.Z"
```
### Creating a Release
1. **Merge to master:**
```bash
git checkout master
git merge dev
git push origin master
```
2. **Create GitHub release:**
```bash
gh release create vX.Y.Z \
--title "vX.Y.Z" \
--notes "Release notes here"
```
3. **Automated workflows run:**
- Build binaries for all platforms
- Publish to crates.io
- Attach binaries to GitHub release
### Release Checklist
- [ ] Version bumped in Cargo.toml
- [ ] CHANGELOG updated (if exists)
- [ ] All tests pass (`cargo test`)
- [ ] Validation script passes (`bash scripts/validate.sh`)
- [ ] Documentation updated
- [ ] Merged to master
- [ ] GitHub release created
- [ ] Binaries built and attached
- [ ] Published to crates.io
---
## 🐛 Debugging
### Debug Logging
Add debug output:
```rust
eprintln!("Debug: {:?}", some_value);
```
View in Claude Code logs or redirect stderr:
**macOS / Linux:**
```bash
**Windows (PowerShell):**
```powershell
### Common Issues
**Build errors:**
```bash
# Clean and rebuild
cargo clean
cargo build
```
**Test failures:**
```bash
# Run specific test with output
cargo test test_name -- --nocapture
```
**Clippy warnings:**
```bash
# See all warnings
cargo clippy --all-targets --all-features
```
---
## 📚 Dependencies
Key dependencies used:
- **serde / serde_json** - JSON parsing and serialization
- **chrono** - Date/time handling for quota timers
- **keyring** - Secure token storage (cross-platform)
- **terminal_size** - Terminal width detection
- **unicode-width** - Text width calculation
### Adding Dependencies
```bash
# Add a new dependency
cargo add dependency-name
# Add a dev dependency
cargo add --dev dev-dependency-name
```
Update `Cargo.toml` and commit changes.
---
## 🤝 Pull Request Process
1. **Fork the repository**
2. **Create a feature branch** from `dev`
3. **Make your changes**
4. **Run validation:** `bash scripts/validate.sh`
5. **Commit with clear messages**
6. **Push to your fork**
7. **Open a Pull Request** against `dev` branch
### PR Guidelines
- Describe what your PR does
- Reference related issues (#123)
- Include test cases for new features
- Update documentation if needed
- Ensure CI passes
---
## 💬 Getting Help
- **Questions:** [GitHub Discussions](https://github.com/ndave92/claude-code-status-line/discussions)
- **Issues:** [GitHub Issues](https://github.com/ndave92/claude-code-status-line/issues)
- **Code Review:** Tag maintainers in your PR
---
## 📄 License
By contributing, you agree that your contributions will be licensed under the MIT License.