README.md

Claude Code Statusline

A color-coded statusline for Claude Code showing model, user, working directory, git branch, context window usage, token counts, and session cost.

Preview

Example statusline with all segments visible in a git repo and 24% context window usage:

Segment	Color	Example
Model	Cyan	Sonnet 4.6
User	Green	nguyens6
CWD	Yellow	~/agent-dashboard/client
Git branch	Magenta	main (hidden outside git repos)
Context bar	Green → Yellow → Red	████████░░ 79%
Tokens	Green / Cyan / Dim	3↑ 2↓ 156586c (green ↑ in, cyan ↓ out, dim c cache reads)
Cost (USD)	Green → Yellow → Red	$0.4231 (session total — shown on API and subscription plans)

Context bar color thresholds:

• Green — under 50% used
• Yellow — 50–79% used
• Red — 80%+ used

Cost color thresholds:

• Green — under $5
• Yellow — $5–$20
• Red — $20+

Requirements

• Python 3.6+
• Git (for branch detection)
• Claude Code 2.x+

Installation

1. Copy both files into your Claude config directory:

# macOS / Linux
cp statusline.py ~/.claude/statusline.py
cp statusline-command.sh ~/.claude/statusline-command.sh
chmod +x ~/.claude/statusline-command.sh

# Windows (Git Bash)
cp statusline.py "$HOME/.claude/statusline.py"
cp statusline-command.sh "$HOME/.claude/statusline-command.sh"

2. Update the path in statusline-command.sh:

Open ~/.claude/statusline-command.sh and replace the path with your own home directory:

#!/usr/bin/env bash
PYTHONUTF8=1 python3 "/your/home/.claude/statusline.py"

On Windows this looks like:

#!/usr/bin/env bash
PYTHONUTF8=1 python3 "C:/Users/YOUR_USERNAME/.claude/statusline.py"

On macOS/Linux:

#!/usr/bin/env bash
python3 "$HOME/.claude/statusline.py"

3. Add to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "bash \"/path/to/home/.claude/statusline-command.sh\""
  }
}

Windows example:

{
  "statusLine": {
    "type": "command",
    "command": "bash \"C:/Users/YOUR_USERNAME/.claude/statusline-command.sh\""
  }
}

macOS/Linux example:

{
  "statusLine": {
    "type": "command",
    "command": "bash \"/home/YOUR_USERNAME/.claude/statusline-command.sh\""
  }
}

4. Restart Claude Code — fully exit and relaunch. Claude Code does not hot-reload settings.json, so the new statusline will not show up until the process is restarted.

Troubleshooting

The statusline still shows the default (e.g. [Model] 📁 cwd) after restarting.

Claude Code resolves statusLine from multiple settings files, in this precedence (later wins):

1. ~/.claude/settings.json (user, global)
2. ~/.claude/settings.local.json (user, local — often overrides the global)
3. <project>/.claude/settings.json (project, shared)
4. <project>/.claude/settings.local.json (project, local)

If any of those later files defines its own statusLine block, it replaces the global one — yours will never run. Grep for it:

grep -l statusLine ~/.claude/settings*.json $(find . -maxdepth 3 -name 'settings*.json' -path '*.claude*' 2>/dev/null)

For each file that defines a competing statusLine, either delete that block (to fall back to the global one) or point it at the same script:

{
  "statusLine": {
    "type": "command",
    "command": "bash \"/path/to/home/.claude/statusline-command.sh\""
  }
}

The statusline is blank / missing segments.

Run the script manually with a sample payload to confirm it works:

echo '{"model":{"display_name":"Sonnet 4.6"},"workspace":{"current_dir":"'"$HOME"'"},"context_window":{"used_percentage":25,"current_usage":{"input_tokens":1000,"output_tokens":500,"cache_read_input_tokens":200}},"cost":{"total_cost_usd":0.4231}}' \
  | sh ~/.claude/statusline-command.sh

If nothing prints, check that python3 is on your PATH and ~/.claude/statusline.py is readable. The script always exits 0 by design so Claude Code never blocks — errors are silent, so test from the shell first.

How It Works

Claude Code pipes a JSON object to the statusline command's stdin on each update. The script reads that JSON, extracts the relevant fields, and prints a color-coded string using ANSI escape codes.

Key fields used from the JSON payload:

{
  "model": { "display_name": "Sonnet 4.6" },
  "workspace": { "current_dir": "C:\\Users\\..." },
  "context_window": {
    "used_percentage": 79,
    "current_usage": {
      "input_tokens": 3,
      "output_tokens": 2,
      "cache_read_input_tokens": 156586
    }
  },
  "cost": { "total_cost_usd": 0.4231 }
}

Customization

Edit statusline.py directly to change colors, reorder segments, or remove ones you don't want. Each segment is clearly labeled with a comment.

Color constants at the top of the file:

CYAN    = '\033[0;36m'
GREEN   = '\033[0;32m'
YELLOW  = '\033[0;33m'
MAGENTA = '\033[0;35m'
RED     = '\033[0;31m'
DIM     = '\033[2m'