🤝 Contributing to Claude Code Enhanced Statusline

February 6, 2026 · View on GitHub

Assalamu'alaikum and Welcome! 🌟

Thank you for your interest in contributing to the Claude Code Enhanced Statusline project! This project is built with love for the Claude Code community, and we warmly welcome contributors from all backgrounds and skill levels.

📋 Table of Contents

🌟 Ways to Contribute

We welcome contributions in many forms! Choose what resonates with your skills and interests:

🐛 Bug Reports & Issues

  • Found a bug? → Report it here
  • System compatibility issues → Help us support more platforms
  • Performance problems → Share your performance observations
  • Configuration troubles → Help us improve user experience

💡 Feature Requests & Ideas

  • Have a brilliant idea? → Suggest it here
  • Check our TODOS.md → Pick an item that interests you
  • Profile system → High priority feature explicitly planned
  • Plugin system → Help extend functionality
  • Performance improvements → Optimization opportunities

🎨 Theme Creation & Design

  • Create beautiful themes → Follow our theme system
  • Custom theme development → Create new themes beyond classic/garden/catppuccin
  • Theme inheritance → Planned future feature
  • Visual improvements → Screenshots, icons, ASCII art

📖 Documentation & Tutorials

  • Improve existing docs → Fix typos, clarify instructions
  • Create video tutorials → Installation, configuration, customization
  • Write blog posts → Share your statusline setup
  • API documentation → Help document module interfaces

🔧 Code Contributions

  • Bug fixes → Resolve reported issues
  • Feature implementation → Build new functionality
  • Performance optimization → Improve response times
  • Security improvements → Enhance safety measures
  • CI/CD pipeline → Critical infrastructure gap (no .github/workflows/)

🧪 Testing & Quality Assurance

  • Expand test coverage → Currently 77 tests, always room for more
  • Cross-platform testing → Test on different OS environments
  • Load testing → High-frequency usage scenarios
  • Security testing → Input validation, path traversal prevention

🚀 Quick Start for Contributors

1️⃣ Choose Your Contribution Style

🔰 First-time contributor?

  • Start with documentation improvements or theme creation
  • Look for issues labeled good first issue or help wanted
  • Check TODOS.md for beginner-friendly items

⚡ Ready to code?

  • Focus on items in TODOS.md marked as High Priority
  • Ocean theme integration → Low complexity, high impact
  • Profile system → Medium complexity, very high demand

🧪 Testing enthusiast?

  • Expand test coverage in tests/ directory
  • Create performance benchmarks
  • Test edge cases and error scenarios

2️⃣ Read the Roadmap

  • Review TODOS.md for comprehensive development roadmap
  • Understand project priorities and planned features
  • See implementation hints and complexity estimates

🛠️ Development Environment Setup

📋 Prerequisites

  1. Core Requirements:

    # Essential tools
bash --version    # 3.2+ minimum (auto-upgrades to modern bash), 5.0+ recommended for development
jq --version      # 1.5+ required, 1.6+ recommended  
git --version     # 2.0+ required, 2.30+ recommended

    🎯 Universal Bash Compatibility: The statusline includes runtime bash detection that automatically finds and uses modern bash when available, with graceful fallback for older versions.

  2. Testing Framework (required for development):

    # macOS with Homebrew
brew install bats-core shellcheck

# Ubuntu/Debian
sudo apt-get install bats shellcheck

# Alternative: Install via npm
npm install -g bats

  3. Optional but Recommended:

    # For enhanced macOS compatibility
brew install coreutils  # (macOS only)

# Cost tracking is built-in (native JSONL) - no extra dependencies

🔧 Project Setup

  1. Fork and Clone:

    # Fork the repository on GitHub first, then:
git clone https://github.com/YOUR-USERNAME/claude-code-statusline.git
cd claude-code-statusline

# Add upstream remote
git remote add upstream https://github.com/rz1989s/claude-code-statusline.git

  2. Install Dependencies:

    # Install npm dependencies for testing
npm install

# Verify setup by running tests
npm test

  3. Setup Pre-commit Hooks (recommended):

    # Install pre-commit framework
pip install pre-commit

# Install hooks (runs shellcheck, validates TOML, etc.)
pre-commit install

# Test hooks manually
pre-commit run --all-files

  4. Verify Installation:

    # Test the statusline directly
./statusline.sh --help

# Run development workflow
npm run dev

✅ Verification Checklist

  • All tests pass: npm test
  • Linting passes: npm run lint
  • Statusline runs: ./statusline.sh --help
  • Can generate config: cp examples/Config.toml ./Config.toml test.toml

🔄 Development Workflow

🌿 Branching Strategy

Current Active Branches:

  • main - Stable production releases
  • nightly - Experimental features for community testing
  • dev - Stable development integration
  • dev6 - Current development: Enhanced settings.json management
# Start from the appropriate base branch
git checkout dev6          # For current development features
git pull upstream dev6

# Alternative: Start from stable dev for general contributions
git checkout dev           # For general development
git pull upstream dev

# Create a feature branch
git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description
# or
git checkout -b docs/documentation-improvement

Branch Selection Guide:

  • Contributing to settings.json features? → Base on dev6
  • General bug fixes or features? → Base on dev
  • Experimental features? → Consider nightly branch
  • Documentation updates? → Any branch, prefer dev6 for current docs

🔄 Development Cycle

  1. Make Your Changes:

    # Edit files as needed
vim lib/themes.sh    # Example: adding Ocean theme

# Test your changes frequently
./statusline.sh # Configuration is automatically loaded

  2. Run Tests & Validation:

    # Clean environment and run full test suite
npm run dev

# Run specific test categories
npm run test:unit          # Fast unit tests
npm run test:integration   # End-to-end tests

# Code quality checks
npm run lint               # ShellCheck main script
npm run lint:all           # Check everything

  3. Verify Your Changes:

    # Test with different configurations
ENV_CONFIG_THEME=garden ./statusline.sh
ENV_CONFIG_THEME=catppuccin ./statusline.sh

# Test configuration generation
cp examples/Config.toml ./Config.toml
./statusline.sh --validate-config

# For dev6 contributors: Test enhanced settings.json features
# Test standard installation (modifies settings.json)
./install.sh --branch=dev6

# Test preserve functionality (skips settings.json)
./install.sh --branch=dev6 --preserve-statusline

# Verify backup creation
ls ~/.claude/settings.json.backup.*

📝 Commit Guidelines

We follow conventional commit format for consistency:

# Format: type(scope): description
# 
# Types: feat, fix, docs, style, refactor, test, chore
# Scope: theme, config, mcp, cost, git, security, etc.

# Examples:
git commit -m "feat(themes): add ocean theme integration"
git commit -m "fix(config): resolve TOML parsing edge case"
git commit -m "docs: update installation guide with new dependencies"
git commit -m "test: add security validation test cases"
git commit -m "refactor(display): optimize output formatting performance"

Commit Message Guidelines:

  • First line: 50 characters or less
  • Body: Wrap at 72 characters, explain the "why"
  • Reference issues: "Closes #123" or "Fixes #456"
  • Breaking changes: Include "BREAKING CHANGE:" in footer

📝 Code Standards & Guidelines

🏗️ Modular Architecture Principles

Our codebase follows a clean modular architecture:

statusline.sh           # Main orchestrator (332 lines)
├── lib/core.sh        # Base utilities, module loading
├── lib/security.sh    # Input validation, sanitization
├── lib/config.sh      # TOML configuration management  
├── lib/themes.sh      # Color theme system
├── lib/git.sh         # Repository status, commits
├── lib/mcp.sh         # MCP server monitoring
├── lib/cost.sh        # Cost tracking integration
└── lib/display.sh     # Output formatting

📋 Coding Standards

  1. Shell Scripting Best Practices:

    # Use strict mode
set -euo pipefail

# Quote variables
echo "$variable" not $variable

# Use local variables in functions
local variable_name="value"

# Handle errors gracefully
command || handle_error "Command failed" 1 "function_name"

  2. Function Structure:

    # Standard function template
function_name() {
    local param1="\$1"
    local param2="${2:-default_value}"
    
    # Validate inputs
    [[ -n "$param1" ]] || { 
        handle_error "Parameter required" 1 "function_name"
        return 1
    }
    
    # Implementation
    # ...
    
    return 0
}

  3. Module Guidelines:

    • Each module must be self-contained
    • Use [[ "${MODULE_LOADED:-}" == "true" ]] && return 0 to prevent double-loading
    • Export MODULE_LOADED=true at the end
    • Follow existing function naming conventions

🎨 Theme Development Standards

When creating new themes:

# Theme function structure in lib/themes.sh
apply_THEME_NAME_theme() {
    # Set all required color variables
    export RED="\\033[31m"
    export BLUE="\\033[34m"
    # ... all basic colors
    
    # Extended colors
    export ORANGE="\\033[38;5;208m"
    # ... extended colors
    
    # Set theme name for display
    export CURRENT_THEME="theme-name"
}

🔐 Security Guidelines

  • Input validation: Use sanitize_path_secure() for all paths
  • Command injection prevention: Quote all variables, use arrays
  • Timeout protection: All external commands must have timeouts
  • Error handling: Never expose sensitive information in error messages

📊 Performance Standards

  • Caching: Use intelligent caching for expensive operations
  • Timeouts: All network operations must have configurable timeouts
  • Parallel execution: Independent operations should run in parallel
  • Memory efficiency: Avoid large temporary files

🧪 Testing Requirements

📋 Test Coverage Expectations

Our project maintains high test coverage standards:

  • Unit Tests: 95%+ function coverage
  • Integration Tests: All major user scenarios
  • Security Tests: All input validation paths
  • Performance Tests: Response time validation

🏃 Running Tests

# Complete test suite (77 tests)
npm test

# Specific test categories  
npm run test:unit          # Individual function tests
npm run test:integration   # End-to-end scenarios
bats tests/benchmarks/     # Performance tests

# Individual test files
bats tests/unit/test_git_functions.bats
bats tests/integration/test_toml_integration.bats

✍️ Writing New Tests

  1. Unit Test Template:

    #!/usr/bin/env bats

load '../setup_suite'
load '../helpers/test_helpers'

setup() {
    common_setup
    setup_mock_environment
}

teardown() {
    common_teardown
}

@test "function should handle normal input correctly" {
    # Arrange
    local input="test input"
    
    # Act
    run my_function "$input"
    
    # Assert
    assert_success
    assert_output_contains "expected output"
}

  2. Integration Test Template:

    @test "full statusline with ocean theme configuration" {
    # Setup ocean theme config
    create_test_config_file "ocean"
    
    # Run statusline with test input
    echo "$TEST_INPUT_JSON" | run ./statusline.sh
    
    # Validate output structure
    assert_success
    validate_statusline_format "$output"
    assert_output_contains "ocean colors"
}

🛠️ Test Utilities Available

# Mock functions (in helpers/test_helpers.bash)
setup_mock_git_repo()              # Create mock git repository
setup_mock_mcp()                   # Mock MCP server responses
create_mock_command()              # Mock any command
validate_statusline_format()       # Validate 4-line output
strip_ansi_codes()                 # Remove colors for testing

✅ Test Requirements for PRs

Before submitting a pull request:

  • All existing tests pass: npm test
  • New functionality has corresponding tests
  • Test coverage remains above 90%
  • Performance tests pass (if applicable)
  • Security tests pass for new input handling

📦 Pull Request Process

🎯 Before You Submit

  1. Complete the Development Checklist:

    • Code follows project standards
    • All tests pass: npm test
    • Linting passes: npm run lint:all
    • Documentation updated (if needed)
    • TODOS.md updated (if implementing a TODO item)

  2. Test Your Changes Thoroughly:

    # Test with different configurations
./statusline.sh # Configuration is automatically loaded
ENV_CONFIG_THEME=garden ./statusline.sh
ENV_CONFIG_THEME=catppuccin ./statusline.sh

# Test edge cases
./statusline.sh --help
cp examples/Config.toml ./Config.toml

📋 PR Submission Guidelines

  1. PR Title Format:

    feat(themes): add ocean theme integration
fix(config): resolve TOML parsing edge case
docs: update contributing guidelines

  2. PR Description Template:

    ## 📋 Summary
Brief description of changes and motivation.

## 🔄 Changes Made
- [ ] Added ocean theme integration
- [ ] Updated lib/themes.sh with ocean colors
- [ ] Added ocean theme tests
- [ ] Updated documentation

## 🧪 Testing
- [ ] All existing tests pass
- [ ] Added new tests for ocean theme
- [ ] Tested with multiple configurations
- [ ] Manual testing completed

## 📖 Documentation  
- [ ] Updated relevant documentation
- [ ] Added theme examples
- [ ] Updated TODOS.md (if applicable)

## 🔗 Related Issues
Closes #123
Related to #456

## 📸 Screenshots (if applicable)
[Add screenshots of visual changes]

  3. PR Size Guidelines:

    • Small PRs preferred → Easier to review, faster to merge
    • One feature per PR → Focused changes, clear purpose
    • Documentation updates → Can be combined with related code changes

🔍 Review Process

  1. Automated Checks:

    • All tests must pass
    • Linting must pass
    • No security vulnerabilities detected

  2. Human Review:

    • Code quality and style consistency
    • Adherence to architectural principles
    • Test coverage and quality
    • Documentation completeness

  3. Merge Requirements:

    • At least one maintainer approval
    • All CI checks passing
    • Conflicts resolved
    • Up-to-date with target branch

🐛 Issue Guidelines

🐛 Bug Reports

Use the bug report template and include:

  1. Environment Information:

    # Run this diagnostic command
./statusline.sh --help
bash --version
jq --version
uname -a

  2. Reproduction Steps:

    • Clear, step-by-step instructions
    • Minimal test case if possible
    • Expected vs. actual behavior

  3. Configuration Details:

    # Include your Config.toml (remove sensitive data)
cat Config.toml

# Or show relevant environment overrides
ENV_CONFIG_THEME=garden ./statusline.sh

💡 Feature Requests

Use the feature request template and include:

  1. Problem Statement: What problem does this solve?
  2. Proposed Solution: How should it work?
  3. Alternative Solutions: What other approaches did you consider?
  4. Use Cases: Who would benefit from this feature?
  5. Implementation Ideas: Any technical suggestions?

🏷️ Issue Labels

We use these labels to organize issues:

  • bug → Something isn't working
  • enhancement → New feature or improvement
  • documentation → Documentation related
  • good first issue → Great for newcomers
  • help wanted → Community help needed
  • priority: high → Critical issues
  • theme → Theme-related changes
  • config → Configuration system changes
  • security → Security-related issues
  • performance → Performance improvements

🏗️ Project Structure Guide

📁 Directory Overview

claude-code-statusline/
├── statusline.sh              # Main orchestrator script (332 lines)
├── lib/                       # Modular components (8 modules)
│   ├── core.sh               # Base utilities, module loading
│   ├── security.sh           # Input sanitization, validation
│   ├── config.sh             # TOML configuration parsing
│   ├── themes.sh             # Color theme management
│   ├── git.sh                # Repository status, commits
│   ├── mcp.sh                # MCP server monitoring
│   ├── cost.sh               # Cost tracking integration
│   └── display.sh            # Output formatting
├── tests/                     # Comprehensive test suite (77 tests)
│   ├── unit/                 # Individual function tests
│   ├── integration/          # End-to-end scenarios
│   ├── benchmarks/           # Performance tests
│   ├── fixtures/             # Mock data and outputs
│   └── helpers/              # Test utilities
├── docs/                      # Documentation
├── examples/                  # Sample configurations
│   └── sample-configs/       # Theme examples (Ocean ready!)
├── Config.toml               # Configuration file
├── version.txt               # Centralized version management
├── TODOS.md                  # Development roadmap
└── install.sh                # Automated installer

🔄 Module Loading System

Understanding how modules work:

  1. Core Module (lib/core.sh):

    • Loaded first by statusline.sh
    • Provides load_module() function
    • Contains shared utilities and constants

  2. Module Dependencies:

    core.sh → (required first)
security.sh → (required by most modules)
config.sh → themes.sh, git.sh, mcp.sh, cost.sh
themes.sh → display.sh  
git.sh, mcp.sh, cost.sh → display.sh
display.sh → (loaded last)

  3. Adding New Modules:

    # Create new module: lib/mymodule.sh
#!/bin/bash
[[ "${MYMODULE_LOADED:-}" == "true" ]] && return 0

# Your module code here

export MYMODULE_LOADED=true

# Load in statusline.sh:
load_module "mymodule" || exit 1

🎨 Theme System Architecture

# Theme system in lib/themes.sh
apply_theme() {
    case "${CONFIG_THEME:-classic}" in
        "classic")   apply_classic_theme ;;
        "garden")    apply_garden_theme ;;
        "catppuccin") apply_catppuccin_theme ;;
        "ocean")     apply_ocean_theme ;;    # Ready to implement!
        "custom")    apply_custom_theme ;;
        *)           apply_classic_theme ;;
    esac
}

🎨 Theme Contribution Guide

🌊 High Priority: Ocean Theme Integration

The Ocean theme is ready to implement - it exists in examples/sample-configs/ocean-theme.toml but needs integration:

  1. Implementation Steps:

    # Add to lib/themes.sh
apply_ocean_theme() {
    # Copy colors from examples/sample-configs/ocean-theme.toml
    export BLUE="\\033[38;2;0;119;190m"     # Deep ocean blue
    export TEAL="\\033[38;2;0;150;136m"     # Teal depths
    # ... etc
}

# Update apply_theme() case statement
"ocean") apply_ocean_theme ;;

  2. Testing Requirements:

    # Test ocean theme
ENV_CONFIG_THEME=ocean ./statusline.sh

# Add ocean theme test
bats tests/integration/test_ocean_theme.bats

🎨 Creating Custom Themes

  1. Design Principles:

    • Readability: Ensure good contrast in terminals
    • Consistency: Use a coherent color palette
    • Accessibility: Consider color-blind users
    • Terminal compatibility: Test in different terminal emulators

  2. Theme Structure:

    apply_THEME_NAME_theme() {
    # Basic ANSI colors (required)
    export RED="\\033[31m"
    export GREEN="\\033[32m"
    export YELLOW="\\033[33m"
    export BLUE="\\033[34m"
    export MAGENTA="\\033[35m"
    export CYAN="\\033[36m"
    export WHITE="\\033[37m"
    
    # Extended colors (optional but recommended)
    export ORANGE="\\033[38;5;208m"
    export PURPLE="\\033[95m"
    export LIGHT_GRAY="\\033[38;5;248m"
    export BRIGHT_GREEN="\\033[92m"
    
    # Formatting (required)
    export DIM="\\033[2m"
    export RESET="\\033[0m"
    
    # Theme identification
    export CURRENT_THEME="theme-name"
}

  3. Testing Your Theme:

    # Quick test
ENV_CONFIG_THEME=your_theme ./statusline.sh

# Generate config with your theme
cp examples/Config.toml ./Config.toml
# Edit Config.toml to set theme.name = "your_theme"
./statusline.sh # Configuration is automatically loaded

📸 Theme Documentation Requirements

When contributing themes:

  • Add theme to examples/sample-configs/
  • Include screenshots in assets/screenshots/
  • Update README.md theme gallery
  • Add theme tests
  • Document color meanings and inspiration

📖 Documentation Contributions

📋 Documentation Standards

  1. Style Guide:

    • Use emoji sections for visual organization 🎯
    • Code blocks with syntax highlighting
    • Clear examples with expected outputs
    • Cross-references between related sections

  2. Structure Requirements:

    • Table of contents for long documents
    • Step-by-step instructions where applicable
    • Troubleshooting sections
    • Links to related documentation

🎯 High-Priority Documentation Needs

  1. Performance Tuning Guide → TODOS.md
  2. API Documentation → Module interface documentation
  3. Plugin Development Guide → For future plugin system
  4. Video Tutorial Series → Installation, configuration, themes
  5. Best Practices Guide → Configuration recommendations

📝 Documentation Workflow

  1. Update Related Files:

    • README.md → For user-facing changes
    • CLAUDE.md → For development-related changes
    • docs/ → For detailed guides
    • TODOS.md → Remove completed items

  2. Validation:

    # Test all code examples in documentation
# Validate all links work
# Check spelling and grammar
# Ensure screenshots are current

🚀 Release Process

📋 Version Management

We use centralized version management with version.txt:

# Current version
cat version.txt        # Example: 1.5.2

# Version sync commands  
./statusline.sh --version-sync       # Sync package.json with version.txt
./statusline.sh --version-check      # Verify consistency

🔄 Release Workflow

  1. Pre-release Checklist:

    • All tests passing: npm test
    • Documentation updated
    • TODOS.md updated with completed items
    • Version bumped appropriately
    • Changelog draft prepared

  2. Version Bump Guidelines:

    • Major (X.0.0): Breaking changes, API removal
    • Minor (0.X.0): New features, backward-compatible
    • Patch (0.0.X): Bug fixes, small improvements

  3. Release Process (For Maintainers):

    # Update version.txt
echo "1.6.0" > version.txt

# Sync package.json
./statusline.sh --version-sync

# Create release commit
git commit -am "release: v1.6.0"
git tag v1.6.0
git push origin dev --tags

📋 Release Notes Format

## v1.6.0 - Ocean Theme Integration 🌊

### ✨ New Features
- Added Ocean theme as built-in option
- Profile system implementation
- Enhanced theme inheritance

### 🐛 Bug Fixes  
- Fixed TOML parsing edge case
- Resolved timeout validation issue

### 📖 Documentation
- Updated theme gallery
- Added contributing guidelines
- Enhanced installation guide

### 🏗️ Internal Improvements
- Improved test coverage to 82%
- Enhanced CI/CD pipeline
- Code quality improvements

🌍 Community Guidelines

🤲 Our Values

This project is built with Islamic values and community spirit:

  • Respect: Treat all contributors with dignity and kindness
  • Patience (Sabr): Be patient with newcomers and different skill levels
  • Gratitude (Shukr): Appreciate all contributions, big and small
  • Excellence (Ihsan): Strive for quality in all work
  • Cooperation (Ta'awun): Work together for the benefit of the community

🗣️ Communication Guidelines

  1. Be Welcoming:

    • Use inclusive language
    • Welcome newcomers warmly
    • Share knowledge generously
    • Celebrate contributions

  2. Be Respectful:

    • Disagree respectfully about code, not people
    • Assume good intentions
    • Give constructive feedback
    • Be open to learning

  3. Be Helpful:

    • Answer questions when you can
    • Point to relevant documentation
    • Share useful resources
    • Mentor newcomers

🚫 Unacceptable Behavior

  • Harassment, discrimination, or offensive language
  • Personal attacks or trolling
  • Spam or off-topic discussions
  • Sharing others' private information
  • Any behavior that creates a hostile environment

📞 Reporting Issues

If you experience or witness unacceptable behavior:

❓ Getting Help

🆘 Where to Get Help

  1. Documentation First:

    • README.md → Installation and basic usage
    • CLAUDE.md → Development guidelines
    • TODOS.md → Implementation roadmap
    • docs/ → Detailed guides

  2. Community Support:

  3. Development Help:

🤔 Common Questions

Q: I'm new to shell scripting. Can I still contribute?
A: Absolutely! Start with documentation, themes, or testing. Everyone's contributions are valuable.

Q: How do I test my changes without affecting my system?
A: Use the test environment and temporary configurations: ./statusline.sh # Configuration is automatically loaded test.toml

Q: What if I break something?
A: Don't worry! That's what tests are for. Run npm test to catch issues early, and the community will help fix any problems.

Q: Can I implement multiple TODO items in one PR?
A: It's better to focus on one feature per PR for easier review. Exception: closely related items can be grouped.

🌟 Thank You!

Jazakallahu khairan for your interest in contributing! Your efforts help make this project better for the entire Claude Code community.

Whether you're fixing a typo, implementing a major feature, or helping other contributors, your work matters. Every contribution, no matter how small, makes a difference.

Barakallahu feek and happy coding! 🚀

Made with ❤️ for the Claude Code community