claude-code-status-bar

Your quota burn, context fill, git state, and live activity, visible under every response.

---

Claude Code warns you about your rate limit and your full context window only once it's already too late to act gracefully. This status bar keeps those numbers, plus your git state, session cost, and what Claude is doing right now, under every response:

~/my-app on ↱ main  ◆ Opus 4.8 (1M)  ███████░░│ 78% of 1M  5hr (2h20m) ███░░│░░░░ 37%  wk (3d4h) ███████░│░ 72%  +42 -7  ● 3 dirty  ↓2 ↑1  12m  $0.45
→ Edit SignupForm.tsx  [Edit 5 · Read 4 · Bash 2]  │  ⚒ research 12s  │  ██░░░ 2/5 Add tests

Line 1: dir · branch · model · context fill · 5h + weekly quota · git state · duration · cost • Line 2: live tool · tool counts · subagent · todos

• Quota: 5-hour and weekly usage with pacing markers showing where you should be for even consumption.
• Context: a colour-coded bar that warns before auto-compact, not after.
• Live activity: a second line of running tools, subagents, and todo progress.
• Cost: session cost and burn rate, colour-coded.

Pure bash, no jq, no compiled binaries, one-line install, eight colour themes. Works on macOS, Linux, and Windows (Git Bash); every network call runs in the background, so the bar itself never blocks. Backed by 171 automated tests on all three platforms (plus ShellCheck) in CI.

Install

macOS / Linux (or Git Bash on Windows):

curl -fsSL https://raw.githubusercontent.com/briansmith80/claude-code-status-bar/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/briansmith80/claude-code-status-bar/main/install.ps1 | iex

The status bar appears after the next Claude Code response (not immediately). It needs only bash and curl, both already required by Claude Code on every OS; git and Node.js are optional and just light up extra segments. Re-running either installer is always safe, and it's also how you update.

Pick a theme (optional): set colour_theme in ~/.claude/statusline.conf or run /claude-code-status-bar:configure, and preview all eight with bash ~/.claude/statusline-command.sh --demo.

1. Download statusline-command.sh, the two optional Node.js helpers (statusline-helper.js for the activity line, statusline-subagent.js for the agent panel rows), and the version file into ~/.claude/.
2. Create ~/.claude/settings.json with a statusLine entry (plus a subagentStatusLine entry when Node.js is available), or merge the missing entries into your existing file without touching your other settings. The bash installer merges using node, python3, or python; the PowerShell installer does it natively.
3. Existing statusLine and subagentStatusLine entries are left untouched, with one exception: commands this installer itself wrote in an older format (MSYS-style /c/... or unquoted paths, which fail under some spawn shells on Windows) are upgraded in place on re-run. Migrating from another status line? Remove your old entry first, then re-run the installer.
4. If the bash installer finds no JSON-capable interpreter, it prints the exact snippets to paste into settings.json yourself.
5. Clear the update-check cache so the new version is picked up immediately.

The status bar runs through Git for Windows, which Claude Code on Windows already requires; the PowerShell installer checks for bash and tells you what to do if it is missing. Avoid piping curl.exe output straight into bash from PowerShell: PowerShell 5.1 re-encodes pipeline data between native programs and can corrupt the script. If you prefer the bash installer from PowerShell, run it as one unit instead: bash -c "curl -fsSL https://raw.githubusercontent.com/briansmith80/claude-code-status-bar/main/install.sh | bash"

Plugin install

If you prefer the Claude Code plugin system:

/plugin marketplace add briansmith80/claude-code-status-bar
/plugin install claude-code-status-bar
/claude-code-status-bar:setup

The plugin ships two slash commands:

Command	What it does
/claude-code-status-bar:setup	Guided install: copies the files from the plugin cache (no network download), configures settings.json (asking before replacing an existing statusLine entry), runs a smoke test, and offers to set a theme and toggles.
/claude-code-status-bar:configure	Interactive editor for ~/.claude/statusline.conf: themes, segment toggles, display options, and grouping, written as a minimal diff against the defaults.

1. Download the files to ~/.claude/:

curl -fsSL https://raw.githubusercontent.com/briansmith80/claude-code-status-bar/main/statusline-command.sh -o ~/.claude/statusline-command.sh
curl -fsSL https://raw.githubusercontent.com/briansmith80/claude-code-status-bar/main/VERSION -o ~/.claude/.statusline-version
# Optional: live activity line (requires Node.js)
curl -fsSL https://raw.githubusercontent.com/briansmith80/claude-code-status-bar/main/statusline-helper.js -o ~/.claude/statusline-helper.js

2. Make it executable: chmod +x ~/.claude/statusline-command.sh
3. Add to ~/.claude/settings.json:

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

Jump to: Configuration · Colour themes · Segments · CLI flags · Updating · Troubleshooting

Highlights

• Auto-compact awareness: the context bar marks the exact point where Claude Code will auto-compact and fires a ▲ warning within 20k tokens of it, on any window size.
• Pacing markers: a │ on each usage bar shows where your usage should be for even consumption, so "37% used" becomes "37% used and comfortably under pace".
• Burn-rate forecast: when you're on track to hit a limit before it resets, the countdown turns into a ▲time-to-limit warning (e.g. ▲1h20m). It stays quiet while you're under pace, so it only speaks up when it matters.
• Model-scoped weekly limits: if your plan carries a per-model weekly cap (the "Fable"/"Opus" row on claude.ai) and it's running hotter than the all-models one, the weekly bar swaps to it — wk:Fable (3d17h) ███░░ 36% — because that's the limit that will actually throttle you.
• Live activity line: running tools, completed tool counts, subagent status, and todo progress, parsed from Claude Code's transcript by an optional Node.js helper.
• Subagent panel rows: a status icon, elapsed time, token cost, and a live tok/s burn rate for every running Task-tool subagent.
• Pure bash, no jq: bash 3.2+ (stock macOS works); JSON is parsed with bash regex, so there's nothing to compile or install on Windows.
• Never blocks: update checks, the usage fallback, and transcript parsing all run in background subshells; the bar renders from caches.

How it compares

There are a lot of Claude Code status lines now. Here's where this one is different from the most popular ones, focused on the things that actually bite you in daily use:

	this	claude-hud	ccstatusline	claude-powerline
Native Windows / Git Bash (one codebase)	✅	⚠️ known bugs	⚠️ needs Node	⚠️ needs Node
No required runtime (pure bash; Node optional)	✅	❌ Node	❌ Node	❌ Node
Runs nothing extra on every render (no npx/node in the hot path)	✅	❌	❌	❌
Pacing marker + burn-rate forecast (▲time-to-limit)	✅	❌	❌	❌
Claude API status early-warning (degraded badge from status.claude.com)	✅	❌	❌	❌
Warns before auto-compact (real CC compact maths)	✅	⚠️ counter	⚠️ counter	⚠️ threshold
Stdin-native limits with OAuth fallback for older CC	✅	⚠️	⚠️	⚠️ vanishes w/o hook data
Checksum-verified self-update (per-release SHA256SUMS)	✅	❌	❌	❌
Live activity (tools/subagents/todos) that degrades w/o Node	✅	✅ (Node-only)	⚠️	⚠️
Guided in-Claude config wizard (/configure)	✅	⚠️	✅ TUI	✅ wizard + web
Automated tests + CI across macOS / Linux / Windows	✅ 187	❌	❌	❌

Snapshot of public docs, June 2026; the others are good tools and evolve quickly — check their repos for the latest. ✅ yes · ⚠️ partial/caveated · ❌ no.

Layouts (1–3 lines)

By default the bar is two lines — line 1 the metrics bar (directory, branch, model, context, usage limits, git state, duration, cost) and line 2 the live activity line. Since v2.19.0 you can rearrange that across up to three lines, putting any segment on any line, in any order.

Pick a preset with layout=:

Preset	Line 1	Line 2	Line 3
classic (default)	all metrics	live activity	—
three-line	model · context · usage · duration · cost	dir · branch · git state	live activity
stacked	dir · branch · model · context · usage · cost	git state · duration	live activity

Or hand-build each line with a space-separated list of segment tokens (these override the preset, per line). Quote any value with spaces — statusline.conf is sourced as shell:

# ~/.claude/statusline.conf
line1="model context usage_5h usage_7d duration cost"
line2="dir branch lines_changed ahead_behind dirty stash pr"
line3="activity"