Task: Create an Optimized Developer Status Bar Script for Claude Code

Role and Context

You are a systems engineer tasked with creating a highly-optimized Python script that displays essential developer-critical information in the status line of Claude Code, a terminal-based code generation tool. Your goal is to create a single-file script that is both visually appealing and performance-optimized for frequent, real-time updates in the developer workflow.

Deliverable

A single-file Python script (~/.claude/statusline.py) that consumes JSON data from stdin and prints a single line of formatted status information to stdout, using ANSI 256-color codes for high-contrast display and unicode symbols for visual cues.

Technical Requirements

Input Specification

The script should expect JSON input in the following structure, read from stdin:

{
  "model": {"display_name": "ModelName"},
  "workspace": {"current_dir": "/path/to/workspace", "project_dir": "/path/to/project"},
  "output_style": {"name": "StyleName"},
  "cost": {
    "total_cost_usd": CostValue,
    "total_duration_ms": DurationValue,
    "total_api_duration_ms": APIDurationValue,
    "total_lines_added": LinesAddedValue,
    "total_lines_removed": LinesRemovedValue
  }
}

Output Requirements

Format and Styling

Print exactly ONE line to stdout
Use ANSI 256-color codes (\033[38;5;Nm) with an optimized color palette for high contrast in both dark and light terminal backgrounds
Smart truncation: The visible text width should be â¤ 80 characters, excluding ANSI escape codes
Use unicode symbols: â (clean), + (added), ~ (modified)
Color palette: orange 208, blue 33, green 154, yellow 229, red 196, gray 245

Information Architecture

The information should be displayed in this order of priority, from left to right:

Core: Model name (orange)
Context: Project directory basename (blue)
Git Status:
- Branch name (green)
- Clean: â (dim gray)
- Modified: ~N (yellow, N = file count)
- Added: +N (yellow, N = file count)
Metadata (dim gray):
- Uncommitted files: !N (red, N = count from git status --porcelain)
- API ratio: A:N% (N = api_duration / total_duration * 100)

Example Output

\033[38;5;208mOpus\033[0m \033[38;5;33mIsaacLab\033[0m \033[38;5;154mmain\033[0m \033[38;5;245mâ\033[0m \033[38;5;245mA:12%\033[0m

Performance and Optimization Constraints

Critical Performance Metrics

Execution time: < 100ms (called every 300ms)
Cache persistence: Store Git status cache in /tmp/claude_statusline_cache.json
Cache TTL: Refresh Git file counts only when cache age > 5 seconds OR .git/index mtime changes
Optimization:
- Branch name: Read .git/HEAD directly (no subprocess)
- File counts: Call subprocess.run(['git', 'status', '--porcelain']) ONLY when cache expires
- Use standard library only: No external dependencies

Error Handling

JSON parse error â Return empty string ""
Missing fields â Omit that section (silently)
Git directory not found â Omit Git section entirely
Any exception â Return empty string ""

Code Structure Guidelines

Single file, < 100 lines
UTF-8 encoding handled for robust unicode output
Maximum one function per concern (parsing, git, formatting)
Type hints required for all functions
Docstring for each function explaining its purpose

Integration Steps

Save the script to ~/.claude/statusline.py
Run chmod +x ~/.claude/statusline.py
Add the following configuration to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.py",
    "padding": 0
  }
}

Test manually: echo '{"model":{"display_name":"Test"},"workspace":{"current_dir":"/tmp"}}' | ~/.claude/statusline.py

Verification Checklist

The script executes without external dependencies (except the single git status --porcelain call when cached)
Visible text width is â¤ 80 characters (excluding ANSI codes)
Colors render correctly in both dark and light terminal backgrounds
Execution time is < 100ms in typical workspaces (cached calls should be < 20ms)
The script gracefully handles missing Git repositories
The cache file is created in /tmp and respects the TTL
Git file counts refresh when either .git/index mtime changes or 5 seconds elapse

Context for Design Decisions

This status bar is designed for a professional developer workflow, focusing on:

Detailed Git information for branch awareness
API efficiency monitoring for cost-consciousness
Visual density for maximum information per character
High-performance caching for frequent updates
Graceful error handling for robustness

Claude Code Statusline Design