STARTER_CHARACTER = 📊

Setup

Update the reference docs to get the latest from Anthropic:

python ~/.claude/skills/writing-statuslines/scripts/update-docs.py

What Status Lines Are

Custom scripts that display contextual information at the bottom of Claude Code's interface. Updated when conversation messages change, at most every 300ms.

Configuration

Add to ~/.claude/settings.json (user-level) or .claude/settings.json (project-level):

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

padding is optional. Set to 0 to let the status line reach the terminal edge.

How It Works

• Claude Code passes session context as JSON via stdin to the script

• First line of stdout becomes the status line text

• ANSI color codes supported

• Script must be executable (chmod +x )

• Only stdout is used (not stderr)

JSON Input Schema

The script receives this via stdin:

{ "hook_event_name": "Status", "session_id": "abc123...", "transcript_path": "/path/to/transcript.json", "cwd": "/current/working/directory", "model": { "id": "claude-opus-4-1", "display_name": "Opus" }, "workspace": { "current_dir": "/current/working/directory", "project_dir": "/original/project/directory" }, "version": "1.0.80", "output_style": { "name": "default" }, "cost": { "total_cost_usd": 0.01234, "total_duration_ms": 45000, "total_api_duration_ms": 2300, "total_lines_added": 156, "total_lines_removed": 23 }, "context_window": { "total_input_tokens": 15234, "total_output_tokens": 4521, "context_window_size": 200000, "used_percentage": 42.5, "remaining_percentage": 57.5, "current_usage": { "input_tokens": 8500, "output_tokens": 1200, "cache_creation_input_tokens": 5000, "cache_read_input_tokens": 2000 } } }

context_window.current_usage may be null if no messages have been sent yet.

Key Fields

• model.display_name — short model name ("Opus", "Sonnet")

• workspace.current_dir / workspace.project_dir — may differ when working in subdirectories

• cost.total_cost_usd — cumulative session cost

• context_window.used_percentage / remaining_percentage — pre-calculated, ready to display

• context_window.current_usage — raw token counts from the last API call

Constraints

• Output exactly one line

• Runs every 300ms at most — expensive operations must be cached

• Keep it scannable: glanceable in under a second

• Script must exit cleanly and quickly

Anti-Patterns

• Cramming too much info — pick 3-4 data points max

• Not consuming stdin (script must read it even if it doesn't use all fields)

• Expensive uncached operations (git commands, API calls) on every invocation

• Multiple output lines (only first line is used)

• Forgetting chmod +x

• Writing to stderr instead of stdout

Testing

Test scripts manually with mock JSON:

echo '{"model":{"display_name":"Sonnet"},"workspace":{"current_dir":"/test"},"cost":{"total_cost_usd":0.05},"context_window":{"used_percentage":42.5}}' | ./statusline.sh

Reference

• references/anthropic-statusline.md - Complete reference with examples in bash, python, and node