ADR-062: Claude Code Statusline Configuration System

Field	Value
Status	Accepted
Date	2026-01-09
Author	Hal Casteel
Reviewers	Claude Opus 4.5
Category	Developer Experience
Tags	statusline, configuration, CLI, UX

1. Executive Summary

This ADR documents the comprehensive statusline configuration system for Claude Code, providing developers with real-time visibility into project state, git status, model usage, system resources, and development environment. The system is fully configurable via JSON, allowing users to toggle sections on/off based on their preferences.

2. Context

2.1 Problem Statement

Claude Code users need immediate visibility into:

Current project context
Git repository state
Model and context window usage
Development environment status
System resource availability
Active task tracking

Without this information readily available, developers must manually check multiple sources, reducing productivity and situational awareness.

2.2 Requirements

Requirement	Priority	Description
Real-time updates	P0	Status must reflect current state
Configurability	P0	Users can toggle sections on/off
Performance	P0	Must not add noticeable latency
Cross-platform	P1	Support macOS and Linux
Color-coded	P1	Visual distinction between status types
Non-intrusive	P1	Multi-line format with logical grouping

3. Decision

Implement a bash-based statusline system with JSON configuration that displays real-time information across 7 configurable sections.

3.1 Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                        Claude Code Runtime                          │
│                              │                                      │
│                              ▼                                      │
│                    ┌─────────────────┐                              │
│                    │   JSON Input    │                              │
│                    │  (stdin pipe)   │                              │
│                    └────────┬────────┘                              │
│                              │                                      │
│                              ▼                                      │
│  ┌────────────────────────────────────────────────────────────┐    │
│  │              statusline-command.sh                          │    │
│  │  ┌──────────────────────────────────────────────────────┐  │    │
│  │  │            Configuration Loader                       │  │    │
│  │  │         ~/.claude/statusline-config.json              │  │    │
│  │  └──────────────────────────────────────────────────────┘  │    │
│  │                          │                                  │    │
│  │         ┌────────────────┼────────────────┐                │    │
│  │         ▼                ▼                ▼                │    │
│  │  ┌──────────┐    ┌──────────┐    ┌──────────┐             │    │
│  │  │ Section  │    │ Section  │    │ Section  │    ...      │    │
│  │  │ Enabled? │    │ Enabled? │    │ Enabled? │             │    │
│  │  └────┬─────┘    └────┬─────┘    └────┬─────┘             │    │
│  │       │               │               │                    │    │
│  │       ▼               ▼               ▼                    │    │
│  │  ┌──────────┐    ┌──────────┐    ┌──────────┐             │    │
│  │  │ Generate │    │ Generate │    │ Generate │             │    │
│  │  │ Content  │    │ Content  │    │ Content  │             │    │
│  │  └────┬─────┘    └────┬─────┘    └────┬─────┘             │    │
│  │       └───────────────┴───────────────┘                    │    │
│  │                       │                                    │    │
│  │                       ▼                                    │    │
│  │              ┌────────────────┐                            │    │
│  │              │   Assemble &   │                            │    │
│  │              │   Output Line  │                            │    │
│  │              └────────────────┘                            │    │
│  └────────────────────────────────────────────────────────────┘    │
│                              │                                      │
│                              ▼                                      │
│                    ┌─────────────────┐                              │
│                    │  Terminal Line  │                              │
│                    └─────────────────┘                              │
└─────────────────────────────────────────────────────────────────────┘

3.2 File Locations

File	Path	Purpose
Script	`~/.claude/statusline-command.sh`	Main statusline generator
Config	`~/.claude/statusline-config.json`	Section toggle configuration
Settings	`~/.claude/settings.json`	Claude Code settings (references script)

4. Statusline Sections

4.1 Section Overview

#	Section	Icon	Key	Default	Description
1	Project	📁	`project`	`true`	Current working directory name
2	Git	⎇	`git`	`true`	Branch, status, sync state
3	Claude	🤖	`claude`	`true`	Model, context usage, tokens
4	Environment	⚙	`environment`	`true`	Dev tools and runtimes
5	System	💻	`system`	`true`	Hardware resources
6	Identity	👤	`identity`	`true`	User, host, time
7	Task	📋	`task`	`true`	Active CODITECT task ID

4.2 Section 2: Git (⎇)

Purpose: Provide comprehensive git repository status at a glance.

Element	Symbol	Color	Description
Branch name	—	Green	Current branch or commit hash
Clean status	✓	Green	Working tree is clean
Dirty status	✗	Red	Uncommitted changes exist
Ahead count	↑n	Green	Commits ahead of remote
Behind count	↓n	Red	Commits behind remote
Stash count	S:n	Yellow	Number of stashed changes
File count	nf	Yellow	Number of changed files

Examples:

Status Line	Meaning
`main✓`	On main, clean
`main✗ 3f`	On main, dirty, 3 files changed
`feature✓↑2`	On feature, clean, 2 ahead
`main✗↑1↓3 S:2 5f`	Dirty, 1 ahead, 3 behind, 2 stashes, 5 files

4.3 Section 3: Claude (🤖)

Purpose: Display model information and context window utilization.

Element	Format	Description
Model name	Opus/Sonnet/Haiku	Current Claude model
Context %	n%	Context window usage percentage
Token flow	nK→nK	Input tokens → Output tokens (in thousands)

Model Colors:

Model	Color	ANSI Code
Opus	Magenta	`\033[35m`
Sonnet	Blue	`\033[34m`
Haiku	Green	`\033[32m`
Unknown	White	`\033[97m`

Context Usage Colors:

Range	Color	Meaning
0-49%	Green	Plenty of room
50-79%	Yellow	Getting full
80-100%	Red	Near limit

4.4 Section 4: Environment (⚙)

Purpose: Show active development tools, runtimes, and project type indicators.

Element	Icon	Color	Condition
Python venv	🐍	Magenta	`$VIRTUAL_ENV` set or `.venv/` exists
Node.js	⬢	Green	`package.json` exists + node installed
Docker	🐳	Blue	Running containers > 0
Rust	🦀	Red	`Cargo.toml` exists
Go	🔷	Cyan	`go.mod` exists
TypeScript	TS	Blue	`tsconfig.json` exists
Version	vX.Y.Z	Dim	From package.json or pyproject.toml

4.5 Section 5: System (💻)

Purpose: Display hardware resource status for awareness of system constraints.

Element	Icon	Color Logic	Source
Battery	🔋/⚡/🪫	Green (charging/ok), Red (<20%)	`pmset -g batt`
Memory	💾	Blue	`vm_stat`
Disk	💿	Dim	`df -h`

Battery Icons:

Icon	Meaning	Condition
⚡	Charging	"charging" in pmset output
🔋	On battery (ok)	>= 20%
🪫	Low battery	< 20%

4.6 Section 7: Task (📋)

Purpose: Display the active CODITECT task ID for project tracking integration.

Element	Color	Source
Task ID	White	`$CODITECT_TASK` environment variable

Condition: Only displays if $CODITECT_TASK is set.

Integration:

export CODITECT_TASK="A.9.1.3"  # Set before starting Claude Code

5. Configuration

5.1 Configuration File

Location: ~/.claude/statusline-config.json

Full Schema:

{
  "_comment": "Toggle sections on/off. Set to false to hide a section.",
  "sections": {
    "project": true,
    "git": true,
    "claude": true,
    "environment": true,
    "system": true,
    "identity": true,
    "task": true
  },
  "_section_descriptions": {
    "project": "📁 Current directory name",
    "git": "⎇ Branch, status, ahead/behind, stash, file count",
    "claude": "🤖 Model name, context %, token usage (in→out)",
    "environment": "⚙ Python venv, Node version, Docker, language icons, package version",
    "system": "💻 Battery, RAM usage, disk space",
    "identity": "👤 User, hostname, time, timezone",
    "task": "📋 Active CODITECT task ID (requires $CODITECT_TASK env var)"
  },
  "_usage": "Edit this file to customize your statusline. Changes take effect immediately."
}

5.2 Preset Configurations

Preset	Sections Enabled	Use Case
Full	All 7	Maximum visibility
Minimal	project, claude	Clean, focused
Dev Focus	project, git, claude, environment	Development work
System Monitor	project, claude, system	Resource-aware
Git Focus	project, git, claude	Version control focus

Minimal Configuration:

{
  "sections": {
    "project": true,
    "git": false,
    "claude": true,
    "environment": false,
    "system": false,
    "identity": false,
    "task": false
  }
}

5.3 Configuration Commands

Action	Command
Edit config	`nano ~/.claude/statusline-config.json`
Enable section	`jq '.sections.system = true' ~/.claude/statusline-config.json \| sponge ~/.claude/statusline-config.json`
Disable section	`jq '.sections.system = false' ~/.claude/statusline-config.json \| sponge ~/.claude/statusline-config.json`
Reset to full	Copy full config from ADR
View current	`cat ~/.claude/statusline-config.json`

6. Color System

6.1 ANSI Color Codes

Color	Code	Escape Sequence	Usage
Cyan	36	`\033[36m`	Separators, username
Green	32	`\033[32m`	Good status, names
Yellow	33	`\033[33m`	Warnings, time
Red	31	`\033[31m`	Errors, alerts
Blue	34	`\033[34m`	Info, Sonnet model
Magenta	35	`\033[35m`	Opus model, Python
Grey	90	`\033[90m`	Brackets, labels
White	97	`\033[97m`	Task ID
Dim	2	`\033[2m`	Secondary info
Reset	0	`\033[0m`	Clear formatting

6.2 Semantic Color Meanings

Color	Semantic Meaning
Green	Positive: clean, ahead, good battery, success
Yellow	Warning: moderate usage, stashes, file changes
Red	Alert: dirty, behind, high usage, low battery
Blue	Informational: memory, Sonnet, Docker
Magenta	Special: Opus, Python
Cyan	Structural: separators, user identity
Grey/Dim	De-emphasized: brackets, secondary data

7. Integration with CODITECT-CORE-INITIAL-SETUP.py

7.1 Installation Flow

CODITECT-CORE-INITIAL-SETUP.py
         │
         ├── Phase 1: Core Installation
         │
         ├── Phase 2: Symlink Creation
         │
         ├── Phase 3: Machine ID Generation
         │
         ├── Phase 4: Context Database
         │
         ├── Phase 5: Hooks Configuration
         │
         └── Phase 6: Statusline Setup  ◀── NEW
                  │
                  ├── Create statusline-command.sh
                  ├── Create statusline-config.json
                  └── Update settings.json

7.2 Setup Function

def setup_statusline(claude_dir: Path) -> None:
    """Configure Claude Code statusline with comprehensive system status."""

    # Create statusline script
    script_path = claude_dir / "statusline-command.sh"
    script_path.write_text(STATUSLINE_SCRIPT)
    script_path.chmod(0o755)

    # Create default configuration (all sections enabled)
    config_path = claude_dir / "statusline-config.json"
    config_path.write_text(json.dumps({
        "sections": {
            "project": True,
            "git": True,
            "claude": True,
            "environment": True,
            "system": True,
            "identity": True,
            "task": True
        }
    }, indent=2))

    # Update settings.json
    settings_path = claude_dir / "settings.json"
    settings = json.loads(settings_path.read_text()) if settings_path.exists() else {}
    settings["statusLine"] = str(script_path)
    settings_path.write_text(json.dumps(settings, indent=2))

    print("✓ Statusline configured")

8. Troubleshooting

8.1 Common Issues

Issue	Cause	Solution
No statusline displayed	Settings not configured	Check `~/.claude/settings.json` has `statusLine`
Sections missing	Config disabled	Check `~/.claude/statusline-config.json`
Git info missing	Not in git repo	Normal - only shows in git repos
Environment empty	No dev tools detected	Normal - only shows detected tools
Colors not showing	Terminal doesn't support	Use terminal with ANSI support
jq errors	jq not installed	`brew install jq` or `apt install jq`

8.2 Debug Commands

# Test statusline manually
echo '{"workspace":{"current_dir":"'"$PWD"'"}}' | bash ~/.claude/statusline-command.sh

# Check configuration
cat ~/.claude/statusline-config.json | jq .

# Verify settings
cat ~/.claude/settings.json | jq .statusLine

# Check script permissions
ls -la ~/.claude/statusline-command.sh

8.3 Reset to Defaults

# Reset configuration to full
cat > ~/.claude/statusline-config.json << 'EOF'
{
  "sections": {
    "project": true,
    "git": true,
    "claude": true,
    "environment": true,
    "system": true,
    "identity": true,
    "task": true
  }
}
EOF

9. Real-World Examples

9.1 Full Configuration Example

Output:

─[📁:coditect-rollout-master]─[⎇:main✗ S:1 5f]─
─[🤖:Opus 55% 85.0K→25.0K]─
─[⚙:🐍venv ⬢22.1.0 🦀 v2.0.0]─[💻:⚡85% 💾8.2GB 💿120Gi]─
─[👤:halcasteel@mac 14:23:45PST]─[📋:A.9.1.3]─

9.2 Minimal Configuration Example

Config:

{
  "sections": {
    "project": true,
    "git": false,
    "claude": true,
    "environment": false,
    "system": false,
    "identity": false,
    "task": false
  }
}

Output:

─[📁:my-project]─
─[🤖:Opus 42% 55.0K→18.2K]─

Clean, focused view with only project and Claude status

10. Performance Considerations

10.1 Execution Time Budget

Section	Typical Time	Optimization
Project	<1ms	Direct variable
Git	10-50ms	Only if in repo
Claude	<1ms	JSON parsing only
Environment	5-20ms	File existence checks
System	20-50ms	System calls
Identity	<5ms	Quick commands
Task	<1ms	Environment variable
Total	40-130ms	Well within budget

10.2 Optimization Techniques

Lazy evaluation: Sections only computed if enabled
Early exit: Git checks abort if not in repo
Cached config: Config read once per invocation
Parallel-safe: No locks or shared state

11. Consequences

Positive

Real-time visibility into all development state
Fully configurable via JSON
Performance optimized with lazy evaluation
Cross-platform support (macOS, Linux)
Color-coded for quick visual scanning
Integrated with CODITECT task tracking

Negative

Shell dependency - Requires bash 4+
jq dependency - Required for JSON parsing
macOS-specific commands for some features

12. References

Document Version: 1.0.0 Last Updated: 2026-01-09 Next Review: 2026-04-09

1. Executive Summary​

2. Context​

2.1 Problem Statement​

2.2 Requirements​

3. Decision​

3.1 Architecture​

3.2 File Locations​

4. Statusline Sections​

4.1 Section Overview​

4.2 Section 2: Git (⎇)​

4.3 Section 3: Claude (🤖)​

4.4 Section 4: Environment (⚙)​

4.5 Section 5: System (💻)​

4.6 Section 7: Task (📋)​

5. Configuration​

5.1 Configuration File​

5.2 Preset Configurations​

5.3 Configuration Commands​

6. Color System​

6.1 ANSI Color Codes​

6.2 Semantic Color Meanings​

7. Integration with CODITECT-CORE-INITIAL-SETUP.py​

7.1 Installation Flow​

7.2 Setup Function​

8. Troubleshooting​

8.1 Common Issues​

8.2 Debug Commands​

8.3 Reset to Defaults​

9. Real-World Examples​

9.1 Full Configuration Example​

9.2 Minimal Configuration Example​

10. Performance Considerations​

10.1 Execution Time Budget​

10.2 Optimization Techniques​

11. Consequences​

Positive​

Negative​

12. References​