Statusline Customization Reference

Config File

Location:

~/.claude/statusline-config.json

Schema

{
  "sections": {
    "model": true,         // Model name (Opus/Sonnet/Haiku)
    "branch": true,        // Git branch name
    "worktree": true,      // Worktree indicator (wt:name)
    "cost": true,          // Session cost ($X.XX)
    "duration": true,      // Session duration (Xm Xs)
    "context_bar": true,   // Context window usage bar
    "plan_limits": true    // Plan limit bars with reset countdowns
  },
  "context_bar_width": 12, // Width of context bar in chars (8-20)
  "plan_bar_width": 10,    // Width of plan limit bar in chars (6-16)
  "theme": "default"       // Color theme name
}

All fields are optional. Missing fields use defaults shown above.

Sections Reference

model

*

branch

worktree

wt:name

cost

duration

context_bar

plan_limits

Plan Limits Bar Characters

• █

  — both 5h and 7d usage at this position

• ▀

  — only 5h usage (top half)

• ▄

  — only 7d usage (bottom half)

• -

  — empty (unused capacity)

Reset Countdown Format

After each percentage, a countdown shows when the limit resets:

• ↻1h40m

  — resets in 1 hour 40 minutes

• ↻3d12h

  — resets in 3 days 12 hours

• ↻now

  — resetting now

Example:

█▄▄------- 5h:18% ↻1h40m 7d:35% ↻3d12h

Context Bar Token Count

After the percentage, a dim token count shows current/max context usage:

• 45% 90k/200k

  — 90k tokens used out of 200k window

• 72% 144k/200k

  — approaching limit
• Only shown when Claude Code provides token data in stdin

Compaction Detection

A bold magenta

⟳

• 25% 50k/200k ⟳

  — compaction just happened (tokens dropped)
• The indicator appears for one render only, then disappears
• Detection works by caching

  total_input_tokens

  between renders; a drop means compaction occurred
• Cache file:

  ~/.claude/.statusline-token-cache

Themes

default

monochrome

minimal

neon

Script Architecture

Data Flow

1. Claude Code pipes JSON session data to stdin
2. Script reads config from

   ~/.claude/statusline-config.json

3. Extracts fields with

   jq

4. Detects git branch and worktree from

   cwd

5. Reads plan usage from non-blocking background cache
6. Renders ANSI-colored output to stdout

Non-Blocking API Cache

• Cache file:

  ~/.claude/.statusline-usage-cache.json

• TTL: 60 seconds
• Mechanism: Background subshell

  ( ... ) &

  fires API call; current render uses stale cache
• Token source: macOS Keychain (

  security find-generic-password -s "Claude Code-credentials"

  )
• API endpoint:

  https://api.anthropic.com/api/oauth/usage

Input JSON Schema (from Claude Code)

{
  "model": { "display_name": "Claude Opus 4.6" },
  "cost": { "total_cost_usd": 1.23, "total_duration_ms": 180000 },
  "context_window": { "used_percentage": 45.2 },
  "cwd": "/path/to/project"
}

Troubleshooting

jq not found

The script requires

jq

brew install jq

No plan limits showing

• Check if cache file exists:

  ls -la ~/.claude/.statusline-usage-cache.json

• Verify Keychain access:

  security find-generic-password -s "Claude Code-credentials" -w | head -c 20

• If Keychain prompts are denied, the API call silently fails — grant access when prompted
• Plan limits only show when both 5h and 7d utilization data are available

Config not taking effect

• Verify JSON syntax:

  jq . ~/.claude/statusline-config.json

• After changing config, the script picks it up on next render (no restart needed)
• To redeploy the script itself after a plugin update, run

  /statusline:install-statusline

Script not executable

chmod +x ~/.claude/statusline-command.sh
# or for project-level:
chmod +x .claude/statusline-command.sh

Reset countdown not showing

• Reset times come from the

  resets_at

  field in the usage API response
• If the field is missing from the API response, no countdown is shown
• Verify with:

  jq '.five_hour.resets_at, .seven_day.resets_at' ~/.claude/.statusline-usage-cache.json