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.

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:

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

{
  "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:

_{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=:

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"

Reorder freely (e.g. activity on top), and set a line to "" to hide that row. Tokens: dir branch model context usage_5h usage_7d lines_changed dirty ahead_behind stash pr duration worktree cost cost_rate vim agent effort fast_mode tokens update activity. A token still obeys its show_* toggle, unknown tokens are ignored, a segment lives on the first line that lists it, and segments you don't list anywhere won't show. The default (no layout/line* set) is byte-identical to previous versions.

Icons

icon_set=classic (the default) keeps the original glyphs; icon_set=modern switches to a more coherent set — directory ↱, branch ⑂, lines-changed ⇄, and a duration ⏱ that fills a previously-empty slot (model ◆ is unchanged). use_icons=false removes all icons regardless of the set.

The live activity line

Active work pops in theme colours while history recedes into dim text:

⠙ Bash npm test 1m24s  │  → Edit SignupForm.tsx  [Edit 5 · Read 4 · Bash 2]  │  ⚒ research 12s  │  ██░░░ 2/5 Add tests

The spinner advances each time the bar re-renders, so it animates faster with a lower refreshInterval (see Label style). When the cached activity ages past activity_fresh_seconds (default 45) the colours drop back to all-dim, so stale data reads as stale. Set activity_colour=false for the classic all-dim line; NO_COLOR and the mono theme degrade to plain text automatically.

Usage limits & pacing

The bar shows your Anthropic usage limits as colour-coded progress bars with reset labels:

5hr (2h20m) ███│░░░░░░ 37%  wk (3d4h) ███████│░░ 72%

• 5hr / wk: the rolling 5-hour and 7-day windows, each with the time remaining until reset.
• wk:Fable (model-scoped swap, on by default): some plans have a per-model weekly cap alongside the all-models one — the "Fable" or "Opus" row on claude.ai's usage page. When that scoped cap is running higher than the all-models one, it binds first, so the weekly bar swaps to it and names the model. Under or at the all-models level, the plain wk bar stays. Pacing marker, countdown, and burn-rate forecast all compute on whichever limit is shown. Set usage_scoped=false for the plain all-models bar always.
• │ pacing marker: where your usage should be for even consumption across the window. Bar past the marker means you are ahead of pace and may hit the limit early; behind it means you have headroom.
• ~ suffix (e.g. 37%~): the data came from the OAuth cache and is stale (more than two refresh intervals old).

Label style: reset time or countdown

By default the label counts down the time remaining (5hr (2h20m), wk (3d4h)). Set usage_label=clock to show the reset moment instead (5hr (2pm), wk (fri,3am)).

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

Configuration

The installers create ~/.claude/statusline.conf on first install: a fully commented copy of statusline.conf.example with every option and its default. Uncomment and edit the lines you want; it's never overwritten by updates. Confirm resolved values any time with --dump-config. A few common ones:

# ~/.claude/statusline.conf
colour_theme=default        # default | nord | dracula | solarized | tokyo-night | catppuccin | matrix | mono
bar_gradient=true           # true = theme ramp | false = flat | heat = fixed green→red
usage_label=countdown       # countdown (2h20m) | clock (2pm)
dir_style=auto              # auto (responsive) | full | basename
show_cost_rate=false        # opt-in: $/hr burn rate
auto_update=false           # opt-in: install new versions in the background

The full list (every segment toggle, the activity-line options, grouping, and timing) lives in statusline.conf.example.

Colour themes

Eight built-in themes, spread across a saturation/temperature ladder so no two read alike. Each preview is a real render of the bar in that theme (the same output --demo prints):

default · bold, bright primary heat gradient

Preview the other seven themes (dracula · tokyo-night · catppuccin · solarized · nord · matrix · mono)

dracula · neon, electric

tokyo-night · deep midnight blue + neon

catppuccin · soft warm pastel

solarized · earthy, vintage

nord · muted, cool steel

matrix · monochrome phosphor green

mono · greyscale, no colour

The named themes render in 24-bit truecolour when your terminal supports it (force with STATUSLINE_TRUECOLOR=1/0), falling back to the nearest 256-colour. default tracks your terminal's own ANSI palette; matrix is a monochrome phosphor-green tribute (removals are dim green, not red); mono and NO_COLOR drop all colour. Set colour_theme in statusline.conf (or run /claude-code-status-bar:configure); it takes effect on the next render, and --dump-config | grep colour_theme confirms it applied.

Updating

When a new version is available you'll see ↑ <version> in the bar (e.g. ↑ 2.18.1), clickable through to that release's notes. The check runs in the background every 6 hours. The simplest way to update is the built-in self-update:

bash ~/.claude/statusline-command.sh --update

It downloads the latest script and helpers, swaps them in only once every file has downloaded, bumps the version, and leaves your settings.json entries alone. It also refreshes statusline.conf.example and, only if you don't have a statusline.conf yet, creates one from it; your existing config is never overwritten. Run --check-update first to see what's current versus latest. (Too old to have --update? Re-running the installer also updates in place.)

Automatic updates (opt-in)

Set auto_update=true in statusline.conf and the bar installs new versions for you: once the background check flags a newer release, it runs the same self-update in a detached background process (it never blocks rendering), serialised with a lock so parallel sessions don't all download at once. A failed or interrupted download changes nothing, and statusline.conf/settings.json are never touched. It stays off by default so the tool never replaces its own executable without you asking.

Uninstall

bash ~/.claude/statusline-command.sh --uninstall

It lists what will be deleted and asks for confirmation, prompts separately before removing statusline.conf (so you can keep your config for a reinstall), and reminds you to remove the statusLine block from ~/.claude/settings.json yourself.

rm -f ~/.claude/statusline-command.sh
rm -f ~/.claude/statusline-helper.js
rm -f ~/.claude/statusline-subagent.js
rm -f ~/.claude/.statusline-version
rm -f ~/.claude/.statusline-update-cache
rm -f ~/.claude/.statusline-usage-cache
rm -f ~/.claude/.statusline-usage-backoff
rm -f ~/.claude/.statusline-activity-cache
rm -f ~/.claude/.statusline-activity-cache.*
rm -f ~/.claude/.statusline-claude-status-cache
rm -rf ~/.claude/.statusline-transcript-cache
rm -f ~/.claude/statusline.conf   # your config; skip this line to keep it

Segments

All segments are on by default except token counts, cost rate, and the Claude API status badge. Zero-valued segments auto-hide (configurable via auto_hide), and segments whose data is missing are simply omitted, so your actual bar is usually shorter than the full list.

Before the first API response of a session, the bar shows a dim Starting... placeholder. That is normal; the real segments appear as soon as Claude Code sends model and context data.

CLI flags

The script normally runs with no arguments, fed JSON on stdin by Claude Code. The flags are for setup, diagnostics, and removal; the handy ones are --update, --demo, --check-update, and --uninstall.

Subagent status line

While Task-tool subagents run, Claude Code shows an agent panel below the prompt. The optional statusline-subagent.js renderer (wired automatically when Node.js is available) restyles those rows to match the status bar and adds live numbers:

⚒ Audit the usage parsing code  1m24s · 12.4k tok · 354 tok/s ▄▅▆▇▇▆█
✓ Verify the rate-limit fix     3m2s · 48.1k tok
✗ security review               41s · 2k tok

{
  "subagentStatusLine": {
    "type": "command",
    "command": "node ~/.claude/statusline-subagent.js"
  }
}

Troubleshooting

• The bar doesn't appear at all. Check that ~/.claude/settings.json has the statusLine entry (the installer skips this step if any statusLine entry already exists, including one from a different status line). Then wait for the next Claude Code response; the bar renders after responses, not on launch.
• The bar disappeared after setting a low refreshInterval. Claude Code aborts an in-flight statusLine run when the next one starts, and an aborted run blanks the bar. If the interval is below the script's runtime, every run is aborted and nothing ever renders. Measure with --benchmark (~285ms on Windows under MSYS bash, well under 100ms on macOS/Linux), then pick an interval comfortably above it: 2+ on Windows, 1 elsewhere.
• The bar just says Starting... Normal. It means Claude Code hasn't sent model or context data yet, which happens at the start of every session.
• A segment I enabled isn't showing. Most segments auto-hide when their value is zero or their data is missing. Run --dump-config to confirm your override took effect, and --dump-stdin to see which fields your Claude Code version actually sends.
• Usage segments are missing. On Claude Code 2.1+ they should appear automatically from stdin. For the OAuth fallback, check credentials exist (see Where the usage data comes from), then clear the caches: rm -f ~/.claude/.statusline-usage-cache ~/.claude/.statusline-usage-backoff. After repeated failures the script waits up to 30 minutes before retrying.
• Usage shows ~ after the percentage. The OAuth data is stale. Usually transient; if it persists, clear the two cache files above.
• The activity line never appears. It needs Node.js on PATH, ~/.claude/statusline-helper.js, and a Claude Code version that sends transcript_path (--dump-stdin reports this as YES/NO). It also lags one refresh behind and hides when its cache is older than activity_ttl_seconds (default 120).
• --check-update shows an old version right after a release. GitHub's raw CDN caches for a few minutes. Try again shortly.

Security

Points that matter for a tool that runs on every response and can read your OAuth token:

• Nothing is downloaded or executed on the render path. This is a copied local script (plus an optional local helper), not an npx/npm exec that resolves a moving version on every keystroke. The only network calls are the opt-in update check and the usage-API fallback, both run in detached background subshells and never on the critical path.
• All cache and temp files are created with umask 077 (owner-readable only).
• The OAuth token is passed to curl via --config - on stdin, so it never appears in the process list. The wget fallback writes the bearer header to a 0600 temp file passed via --config (never on argv, where ps aux could read it) and runs with --max-redirect=0 to prevent token leakage on redirects; curl is still strongly preferred.
• The self-updater (--update and the opt-in auto_update) and the installers (install.sh / install.ps1, which double as the update path) verify every downloaded file against a per-release SHA256SUMS before installing it, and abort on any mismatch leaving the install untouched. The update source can only be set by a real environment variable, never by statusline.conf.
• Branch names, paths, worktree names, the model and vim-mode labels, and all transcript-derived text are stripped of ANSI escapes and control characters before being printed. Both status-bar lines are printed with printf '%s' (never %b), so escape text embedded in an untrusted field (for example a maliciously named directory) is shown literally and can never decode into a live terminal control sequence.
• ~/.claude/statusline.conf is sourced as bash; it has the same trust level as your .bashrc. The helper stores activity summaries, not transcript content (tool names, file basenames, and short snippets, 30-50 chars at most).

More

flowchart LR
    CC["Claude Code"] -->|"JSON on stdin"| S["statusline-command.sh"]
    S --> L["Lines 1–3 (per layout)"]
    S -.->|"background, every 6h"| U["Version check (GitHub)"]
    S -.->|"background, only without stdin limits"| O["OAuth usage API"]
    S -.->|"background, every refresh"| H["statusline-helper.js parses the transcript"]
    U & O & H -.->|"write"| C["caches in ~/.claude/"]
    C -.->|"read next refresh"| S

claude-code-status-bar/
├── README.md
├── CHANGELOG.md                  # release history
├── LICENSE                       # MIT
├── VERSION                       # single source of truth for the version
├── install.sh                    # one-line installer / updater (macOS, Linux, Git Bash)
├── install.ps1                   # one-line installer / updater (Windows PowerShell)
├── statusline-command.sh         # the status bar (pure bash, installed to ~/.claude/)
├── statusline-helper.js          # optional Node.js transcript parser (live activity line)
├── statusline-subagent.js        # optional Node.js renderer for the subagent panel rows
├── docs/
│   ├── assets/                   # README images + generators (hero, animated demo, per-theme previews under themes/)
│   └── enhancement-backlog.md    # backlog, parked ideas, competitive landscape, principles
├── commands/
│   ├── setup.md                  # /claude-code-status-bar:setup
│   └── configure.md              # /claude-code-status-bar:configure
├── .claude-plugin/
│   ├── plugin.json               # plugin manifest
│   └── marketplace.json          # marketplace catalog for /plugin marketplace add
├── .github/workflows/
│   ├── shellcheck.yml            # lint (pushes to main, PRs)
│   └── tests.yml                 # BATS suite on Linux, macOS, Windows (MSYS2)
├── tests/                        # 146 BATS tests across 15 files
└── CLAUDE.md                     # project guide for working on this repo with Claude Code

brew install bats-core            # macOS
sudo apt-get install -y bats      # Debian / Ubuntu
# Windows (Git Bash / MSYS2): no pacman package; clone bats-core
git clone --depth 1 https://github.com/bats-core/bats-core.git ~/bats-core

bats tests/                       # macOS / Linux
~/bats-core/bin/bats tests/       # Windows

Changelog

Full release history lives in CHANGELOG.md. Recent highlights:

• 2.24.0: Model-scoped weekly limits — when your plan's per-model weekly cap (the "Fable"/"Opus" row on claude.ai) is running higher than the all-models one, the weekly bar swaps to it: wk:Fable (3d17h) ███░░ 36%. On by default, fail-silent, usage_scoped=false to disable.
• 2.23.0–2.23.2: Opt-in Claude API status badge (degraded-only early warning fed by status.claude.com), plus a fix for doubled backslashes in Windows paths.
• 2.22.0 / 2.22.1: Burn-rate forecast — a ▲time-to-limit warning when you're on track to hit a limit before it resets — plus a guided /configure wizard, and a fix so stale todos no longer linger on the activity line.
• 2.21.0: Performance — the live-activity helper now runs only when the line can actually change instead of on every render, so idle sessions stop re-spawning Node; every visual effect (spinner, flash, heat, fade) is unchanged.
• 2.20.0–2.20.2: Security & performance hardening — checksum-verified (SHA256SUMS) self-update and installers, a line-1 control-sequence-injection fix, restored never-block guarantees, and opt-in git_untracked / git_timeout knobs for large or network-mounted repos.
• 2.19.0: Customizable multi-line layout — layout presets plus line1/line2/line3 token overrides (up to three lines), and a refreshed icon_set=modern.
• 2.18.0: Better defaults out of the box: gradient bars on, a responsive dir_style=auto that collapses a long path before any segment is dropped, and a commented statusline.conf the installers create.
• 2.14.0: The named themes redesigned in 24-bit truecolour (with a 256-colour fallback) and spread across a saturation/temperature ladder so no two read alike.

License

MIT, see LICENSE.