powerline-claude-code

Powerline segments for Claude Code, rendered in your tmux status bar (not Claude's own status row):

• status — one mode-switching segment. Normally shows your subscription quota; when an agent needs you it takes over and cycles through the tmux windows that are waiting:

  quiet:    ◧ 5h 47% · 2h13m · ~1h to cap
  waiting:  ✓ 0:nvim (1/2)      ← green, "done, your move"
            ⚠ work:docs (2/2)   ← yellow, "needs a decision"
  

status is the recommended single slot. quota, attention, and usage are also exported if you'd rather place them separately.

Why a capture step

The real /usage numbers (rate_limits) are delivered only to a Claude Code statusLine command — never to hooks, and nowhere on disk. So this plugin installs a tiny statusLine that snapshots rate_limits to a cache the segment reads. Attention is driven by hooks. setup wires up both:

Claude Code ─statusLine JSON─▶ powerline-claude-code statusline ─▶ ~/.cache/.../rate_limits.json ─┐
Claude Code ─Notification/Stop hook─▶ powerline-claude-code hook ─▶ ~/.claude/attention/$TMUX_PANE ┤
                                                                                                   ▼
                                                          powerline  status  segment  (tmux bar)

If you already have a statusLine (e.g. ccstatusline), setup chains it — your existing line keeps rendering while we siphon the quota data.

Install

pipx inject powerline-status \
    git+https://github.com/cwood/powerline-claude-code@master \
    --force --pip-args='--upgrade'

powerline-claude-code setup     # installs hooks + statusLine capture
powerline-claude-code doctor    # ✓/✗ on every moving part

setup is idempotent and preserves any other hooks/statusLine you have. Quota shows up after your next Claude Code turn (Pro/Max only).

Configure

Add one segment to your powerline tmux theme JSON:

{ "function": "powerline_claude_code.status", "priority": 30 }

status arguments

Highlight groups

Define these in your tmux colorscheme. Reason = color is the whole point — background-color the chip so a waiting window is unmissable:

"claude_code:attention_done":             { "fg": "black",  "bg": "green",        "attrs": ["bold"] },
"claude_code:attention_permission":       { "fg": "black",  "bg": "yellow",       "attrs": ["bold"] },
"claude_code:attention_permission_pulse": { "fg": "yellow", "bg": "darkestyellow","attrs": ["bold"] },
"claude_code:attention_idle":             { "fg": "black",  "bg": "darkyellow" },
"claude_code:quota":      { "fg": "gray10", "bg": "gray4" },
"claude_code:quota_warn": { "fg": "black",  "bg": "yellow" },
"claude_code:quota_crit": { "fg": "white",  "bg": "red", "attrs": ["bold"] },
"claude_code:divider":    { "fg": "gray6",  "bg": "gray4" }

Color names come from your powerline color palette. Want it to flash without pulse? Add "attrs": ["blink"] to a group (ignored by alacritty/ghostty — use pulse there). Each group falls back to a generic powerline group then background, so undefined ones still render legibly.

attention_idle / attention_done / attention_permission map to the Stop, Notification(idle_prompt), and Notification(permission_prompt) hooks respectively.

Token volume (opt-in, for API billing)

usage reports raw token volume from transcripts — useful on API billing, not subscriptions:

{ "function": "powerline_claude_code.usage", "args": { "metric": "new" }, "priority": 25 }

Other args: windows (default [5, 30, 60] minutes), spike_ratio (2.0), glyph (Σ), show_zero (false).

Uninstall

powerline-claude-code setup --uninstall   # removes our hooks, restores any chained statusLine
pipx uninject powerline-status powerline-claude-code