statusline-creator

Statusline Creator

Creates Claude Code statusline scripts from composable items with full JSON schema awareness.

Quick Generate

# List available items
~/.claude/skills/statusline-creator/scripts/generate-statusline.sh --list

# Generate 2-line statusline with common items
~/.claude/skills/statusline-creator/scripts/generate-statusline.sh \
  --items "model,dir,git,git-sync,context-bar,cost,duration" \
  --lines 2 --install

# Test with mock data
echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/tmp/test"},"context_window":{"used_percentage":42,"context_window_size":200000},"cost":{"total_cost_usd":0.05,"total_duration_ms":120000}}' | bash ~/.claude/statusline-command.sh

How Statuslines Work

1. Add statusLine to ~/.claude/settings.json:

   {"statusLine": {"type": "command", "command": "bash ~/.claude/statusline-command.sh"}}
   

2. Claude Code pipes JSON session data to your script via stdin after each assistant message
3. Your script reads JSON, extracts fields, prints formatted text to stdout
4. Each echo/printf = one row in the status bar

Timing: runs after each assistant message, debounced at 300ms. Cancelled if new update triggers while running.

Available Items (20 composable blocks)

Item	Category	Description
model	Display	Model name ("Opus")
model-full	Display	Model + 1M context indicator
dir	Display	Working directory basename
session-id	Display	Short session ID (8 chars)
style	Display	Output style name
vim-mode	Display	Vim mode ([N]/[I])
agent	Display	Agent name when using --agent
worktree	Display	Worktree name indicator
context-bar	Context	Progress bar with color thresholds
context-pct	Context	Percentage number only
tokens	Context	Detailed in/out token counts (K)
warn-200k	Context	Warning when >200K tokens
cost	Metrics	Session cost ($X.XX)
cost-color	Metrics	Cost with green/yellow/red thresholds
duration	Metrics	Wall-clock time (Xm Ys)
api-duration	Metrics	API response time only
lines-changed	Metrics	Lines +added -removed
git	Git	Branch + staged/modified (5s cache)
git-sync	Git	Upstream ahead/behind arrows
git-link	Git	Clickable OSC 8 repo link

Writing Custom Items

If the generator doesn't cover your use case, write items manually. See references/item-recipes.md for copy-paste bash snippets for each item.

For the complete JSON schema with all available fields, see references/json-schema.md.

Key patterns:

• Always handle null: jq -r '.field // 0' or jq -r '.field // empty'
• ANSI colors: \033[32m green, \033[33m yellow, \033[31m red, \033[0m reset
• OSC 8 links: \033]8;;URL\aText\033]8;;\a (iTerm2, Kitty, WezTerm only)
• Cache expensive ops: git commands in /tmp/statusline-* with 5s TTL
• Use printf '%b' over echo -e for reliable escape handling

Presets

Minimal (1-line):

generate-statusline.sh --items "model,context-pct,cost" --lines 1

Standard (2-line, recommended):

generate-statusline.sh --items "model,dir,git,git-sync,context-bar,cost-color,duration" --lines 2

Full (3-line):

generate-statusline.sh --items "model-full,dir,git,git-sync,worktree,agent,context-bar,tokens,warn-200k,cost-color,duration,lines-changed" --lines 3

Troubleshooting

Symptom	Fix
Not appearing	chmod +x the script; check disableAllHooks isn't true
Shows -- or empty	Fields null before first API call; use // 0 fallbacks
Colors garbled	Use printf '%b' instead of echo -e
Links not clickable	Terminal must support OSC 8 (iTerm2, Kitty, WezTerm)
Stale values after edit	Changes appear on next assistant message, not immediately
Script errors → blank	Non-zero exit or no output = blank status bar

See Also

• context-bar skill — quick context usage display (subset of this skill)
• Official docs — Claude Code statusline reference
• ccstatusline — community powerline-style statusline