Claude Status Bar

Lightweight status-line monitor for Claude Code, with a local AgentParty bridge for Codex workflows. In Claude Code it shows your 5h / 7d rate-limit usage, reset timers, current model, context window, prompt-cache freshness, and (optionally) session cost. In Codex + AgentParty workflows it can append the current AgentParty channel, identity, listener, unread count, and last-message preview from a local cache.

5h[   27%    ]⏰1h28m →42% | 7d[   79%    ]⏰11h28m →88% | Opus 4.8(350.0k/1.0M) | cache 4m23s

📖 Deep dive: Is that cache 4m23s line actually accurate? — how the prompt-cache countdown is computed

3 styles × 9 themes, configurable in one command. Auto-updates from PyPI. For Claude Code, run pip install claude-statusbar && cs --setup and restart Claude Code.

Contents

• Latest release
• What it shows
• Claude Code vs Codex support
• Install
• Styles & themes
• Configuration
• Fast mode (daemon)
• Slash commands
• cs doctor — self-diagnostic
• Usage cheatsheet
• Environment variables
• How the cache countdown works
• Troubleshooting
• Upgrading
• Comparison with alternatives
• Integrations
• Contributing
• Acknowledgments
• Contributors

Latest release

v3.29.12 (2026-07-15) — AgentParty status is session-correct end to end: sessions sharing one project now read channel, identity, unread count, message preview, and listener state from their own config-owned cache slot instead of mixing those fields with the workspace's last writer.

v3.29.11 (2026-07-11) — AgentParty identity is session-correct: two Claude Code sessions in the same project can use different AGENTPARTY_CONFIG files without both status bars collapsing to the last writer's agent name. Only config paths from actual shell tool calls count; paths quoted in chat do not override identity.

v3.29.6 (2026-07-10) — support docs cleanup: the README now states the support boundary explicitly. Claude Code is the full native statusLine integration; Codex support is the AgentParty local status bridge and does not include OpenAI quota/session accounting.

v3.29.5 (2026-07-09) — service daemon and AgentParty session fixes: cs daemon stop and upgrade drift-kill now recognize launchd/systemd-managed daemons, pidfile cleanup no longer deletes a newer daemon owner's pidfile, and the AgentParty block is gated on session transcript evidence so unrelated windows in the same repo do not inherit another agent's channel line.

v3.29.0 (2026-07-09) — AgentParty block redesign + daemon-restart fixes. The AgentParty line was unreadable (FAINT stacked on the dimmest grey) and always claimed watch down: the reader looked for heartbeat_at while the contract writes heartbeat_ts, so every live listener read as dead. Now it renders as two lines with monochrome glyphs that inherit the theme — a header that states the listening state outright, and the last message on its own line marked ● unread / ○ read and @ when it mentions you. Also fixes three daemon defects found while chasing "I upgraded but nothing changed": the code-drift tick burned its own 30s spawn debounce and left every session inline-rendering; _signal_outdated_daemon could SIGTERM a recycled PID belonging to an unrelated process; and the orphan-.tmp sweep + auto-update check were starved by sharing a timer seeded to daemon start (a daemon that restarts on drift never lived the 30 minutes needed to fire either).

v3.28.2 (2026-07-09) — uv-tool upgrade fix: cs upgrade now detects uv-tool Python symlinks correctly and selects uv tool install --upgrade claude-statusbar.

v3.28.1 (2026-07-09) — upgrade/version UX fix: cs upgrade upgrades the install channel that is actually running cs (uv tool, pipx, or plain pip), and cs -v, cs -V, cs -version all work like cs --version.

v3.28.0 (2026-07-09) — AgentParty / Codex bridge line (show_party, default on): when the same workspace has AgentParty local status, cs appends 🎈 #channel · 🤖/👤 name · 👂watch/serve · unread · last message under the project line. This is local-only (~/.agentparty/state/<workspaceId>/statusline.json), uses the same cwd-scoped workspace id fixtures as AgentParty, and marks stale/down listener state instead of pretending it is live.

v3.27.0 (2026-07-03) — IP-risk detection aligned with ip-check: China-cloud provider detection and ban-risk threshold handling now match the ip-check.leeguoo.com classifier.

v3.11.0 (2026-06-02) — rate-limit projections (show_projection, default on): after each ⏰<reset> timer the bar shows →NN%, your expected end-of-window usage. The 5h model blends recent pace, whole-window average, and a local baseline; the 7d model integrates learned coarse rhythm buckets (work hours, non-work hours, night, weekend) so a busy first day is not blindly extrapolated across the whole week. show_forecast remains the separate ⚠<eta> warning chip for imminent cap hits. Plus: context_window.used_percentage = null handled gracefully, and the daemon only renders windows active in the last 10s.

v3.10.0 (2026-06-02) — live-activity line (in-progress todo, active tool, completed-tool rollup), git ahead/behind + session duration/lines on the project line, running-subagent lines, an opt-in bar_shimmer starfield on the battery bars, and a self-hosted plugin marketplace. Plus: auto-update now actually runs in daemon mode (detached, non-blocking), and the cache countdown is per-session-correct. All new segments are opt-in except the todo line.

v3.6.0 (2026-05-08) — cs --setup now defaults to daemon (fast) mode: under 1% CPU continuously instead of ~3% inline. Pass --inline to opt back. Also: py3.9 compat fixes, GitHub Actions CI, animated hero GIF.

v3.5.1 — npx skills add install path, show_cache_age on by default.

v3.5.0 — consolidated claude-statusbar skill: say "switch theme to nord" / "余量颜色改成 #4ec85b" and Claude Code routes it to the right cs command.

v3.4 — per-segment color management (each metric colors itself by its own severity), classic style finally respects themes, two new themes (catppuccin-mocha, tokyo-night), per-severity color overrides via cs config set color_ok|warn|hot.

v3.2 — daemon fast-mode (now the default in v3.6.0) for ~5× lower CPU at refreshInterval=1.

📋 Full changelog: CHANGELOG.md · GitHub Releases — every version's changes, also linked from the PyPI page.

What it shows

5h[   27%    ]⏰1h28m →42% | 7d[   79%    ]⏰11h28m →88% | Opus 4.8(350.0k/1.0M) | cache 4m23s | $ 1.42
⤷ claude-code-usage-bar ⎇ main● · +182 -47 · ⏱ 12m · v3.12.0
⚙ effort:high · think:on · fast:off · style:default