Bangarang

A status line for Claude Code: everything worth watching in two rows, in a rainbow box.

What it shows

• Top row: BANGARANG (or your own word), then Claude's service status from status.claude.com (Claude operational, or ✕ Claude Outage / ✕ Claude Maintenance in amber, orange or red by severity), then bars for the context window, the refill of your 5-hour limit (it fills up as the refill nears, with the time left beside it), and how long the prompt cache stays warm (… until a session's first reply, when Claude Code starts tracking it; 0% once it has lapsed).
• Bottom row: model, effort, fast mode, your plan, what the session would cost at API prices (Claude Code's own estimate; a plan doesn't bill it) and the month's running total of the same, then bars for the 5-hour and weekly limits, plus per-model limits such as Fable's if you turn them on.
• Remote Control: while the session is connected to Remote Control (/rc, or claude --rc), the top edge of the box reads ● Remote Control. If the connection ends (a lapsed login, say), it reads ○ Remote Control off in amber until you reconnect. A session that never connected keeps a plain box, and the rows never move either way.
• Limit numbers turn amber from 70% and red from 90%. The lighter cells on a limit bar show where your current pace lands by the time it resets.
• The rows line up as a table whatever the model, effort or status: BANGARANG grows or shrinks to take up the slack.

Requirements

• macOS or Linux. The tests run on macOS, Ubuntu 22.04 and Ubuntu 24.04 on every push.
• Claude Code 2.1.278 or later, for the limit and cache numbers
• jq (brew install jq, or sudo apt install jq)
• A terminal with 24-bit colour on a dark background, about 125 columns wide. Made in Terminal.app with SF Mono; most Linux terminals do 24-bit colour too.
• python3, only for running the tests

Install

git clone https://github.com/AdamMackey/bangarang.git ~/Bangarang
cd ~/Bangarang
./install.sh

Then add this to ~/.claude/settings.json:

"statusLine": {
  "type": "command",
  "command": "~/.claude/statusline.sh",
  "refreshInterval": 60
}

It shows up at Claude Code's next refresh. install.sh runs the tests first and keeps any status line you already had as ~/.claude/statusline.sh.bak. Run it again after pulling updates.

Per-model limits (optional)

Claude Code doesn't give status lines the per-model weekly limits (such as Fable's). Add --usage to the command ("command": "~/.claude/statusline.sh --usage"), or set BANGARANG_USAGE=1, and Bangarang runs Claude Code's own /usage headless every 10 minutes in the background to read them. That makes no model call and costs nothing, but it does start a claude process, so it's off unless you turn it on.

Your own word

BANGARANG is the default. Swap in whatever word you like with --phrase:

"command": "~/.claude/statusline.sh --phrase LFG"

or set BANGARANG_PHRASE=LFG. It gets the same letter-spacing, chevrons and rainbow, and still fits the rows exactly. A short word in capitals looks best. Options go together, as in ~/.claude/statusline.sh --usage --phrase LFG.

Running total

The second dollar figure, in whole dollars after the session's own ($1,234), is the month so far: what all your sessions would have cost at API prices. Bangarang keeps the total itself, so it counts from the day you install it. Each session adds only what it spends while the status line runs, so refreshing or resuming never counts the same dollars twice. Only the month shows on the line; for every month and the lifetime total, run

~/.claude/statusline.sh --spend

It's on unless you add --no-monthly to the command (or set BANGARANG_MONTHLY=0), which takes the figure off the line and stops the per-session files.

What it reads and fetches

• The session JSON Claude Code pipes to status lines: model, effort, fast mode, context window, cost, rate limits and the prompt cache.
• Your plan tier (oauthAccount.organizationRateLimitTier) from ~/.claude.json, and nothing else from that file.
• Whether the session is connected to Remote Control, from the small file Claude Code keeps for each running session (~/.claude/sessions/<pid>.json, or under $CLAUDE_CONFIG_DIR). Only whether its Remote Control id is set is read; the id itself is never shown or kept.
• status.claude.com's public status, fetched with curl in the background at most every 2 minutes; a verdict counts for 20 minutes.
• With --usage, Claude Code's /usage every 10 minutes.
• Its caches live in ~/Library/Caches/claude-statusline on macOS and ~/.cache/claude-statusline (or $XDG_CACHE_HOME) on Linux.
• The running total is one small file per session (the session's id, its last cost and what it added each month) in ~/Library/Application Support/Bangarang/spend on macOS and ~/.local/share/bangarang/spend (or $XDG_DATA_HOME) on Linux. Nothing leaves your machine.

Tips

• /color red (or blue, green, yellow, purple, orange, pink, cyan) colours the prompt bar and session name just above the status line. That's Claude Code's, and it's per session.
• The line under the status line (⏵⏵ auto mode on …) belongs to Claude Code and can't be changed.

Development

tests/run.sh          # the test suite (a throwaway HOME; your real cache is never touched)
                      # GitHub Actions runs it on macOS and Ubuntu for every push
tools/preview.sh      # renders tools/sample-payload.json to preview.png and prints it

• tools/ansi2png.py draws ANSI output to a PNG (SF Mono, hearts from Menlo) to check colours.
• tools/tui-harness.py runs a throwaway claude --bare in a pseudo-terminal and prints the screen it draws, through pyte (python3 -m venv tools/venv && tools/venv/bin/pip install pyte). It sets CLAUDE_CODE_NO_FLICKER=1, which forces the full-screen renderer and skips its boot canary: otherwise killing a full-screen launch within 10 seconds of its first frame counts a strike in ~/.claude.json, and two strikes turn full-screen off for that version. CLAUDE_CODE_SANDBOXED=1 skips the trust prompt without saving trust.
• tools/*.swift check font coverage and windows (swift tools/fontcheck.swift).

Things learned the hard way

• Claude Code draws uncoloured status text as faint grey, so every piece has an explicit 24-bit colour. It repeats every colour code of the lines above at the start of each line, so long rows of codes (the box rules) end with a single reset.
• Claude Code only rewrites cells that changed, and Terminal.app can leave a row blank on screen after its window has been hidden, while its text buffer still holds it. A box that never changed would stay blank, so its colours step one unit of blue on odd minutes (invisible), and every refresh repaints it.
• SF Mono has the box-drawing glyphs, and its vertical line runs past the line height, so the sides join up.

Support

Bangarang is free. If it saves you from a surprise limit or two, you can buy me a coffee.

More from MackEye Apps

Bangarang is one of the small apps from MackEye Apps: Mac utilities like Desktop Please and Hold Please, and tools for Claude like Meterous and Pulseous. See them all at mackeye.app.

License

MIT. Not affiliated with Anthropic.