convez.ai
AgenteProdutividadeIntermediário
henryavila

ClaudeBar

henryavila/claudebar

Statusline com medidores de quota para Claude Code com tmux e agentes ativos

Ver no GitHub
InicialPluginScore · de 0 a 100

Statusline de duas linhas para Claude Code que exibe monitoramento de taxa de limite e contexto em tempo real. Mostra indicadores de consumo (estilo pip), integração com tmux, suporte a agentes ativos e configuração completa via TOML. Essencial para gerenciar quotas em sessões de subscriber.

Instalação

$npx convez-ai henryavila/claudebar

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
v1.6.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Monitorar consumo de contexto, taxa horária e semanal durante sessões longas
  • Integrar múltiplas sessões Claude em tmux com identificação automática de pane
  • Alertar visualmente quando se aproxima de limites de quota via cores e zonas
  • Rastrear estado de worktrees, branches e PRs enquanto trabalha com Claude Code

Veredito

Ferramenta altamente especializada para power users de Claude Code que precisam de visibilidade precisa sobre quotas. Implementação robusta com configuração granular, mas nicho específico — valor máximo apenas para quem trabalha com subscriber tier e sessões longas em tmux.

README

A tradução para o português deste README ainda está na fila.

claudebar

npm version npm downloads license node

A two-row, zone-driven statusline for Claude Code. Designed for the subscriber tier: rate-limit awareness matters more than dollar cost.

What it does

Reads the JSON session context Claude Code feeds it via stdin after every message, and prints two ANSI-colored rows:

✦ Opus 4.7 · HIGH · tmux:session:1.2  owner/repo › ⎇  branch  3   #1234 ⏳
ctx ▰▰▱▱▱▱▱▱▱▱ 23%   5h  ▰▰▰▱▱▱▱▱▱▱ 34%   7d  ▰▰▰▰▰▰▱▱▱▱ 62%

Identity row (top) — what session is this? Fuel-gauge row (bottom) — how much runway do I have?

Features

  • Pip-style fuel gauges with zone-driven colors: green <60%, yellow 60-89%, red ≥90% — applied independently to context window, 5-hour rate limit, and 7-day rate limit. The bar shape tells you "how full"; the color tells you "how worried".
  • Quota reset countdown + time-elapsed marker on the 5h and 7d chips: 5h · 2h18m ▰▰▰▰│▰▰▱▱▱▱ 60%. The text tells you when the window resets; the │ inside the bar shows how far into the window you already are. When the marker is inside the fill, you're burning faster than time allows; past the fill, you have margin.
  • GLM Coding Plan support: when Claude Code is pointed at a GLM endpoint (api.z.ai, open.bigmodel.cn, or dev.bigmodel.cn), the 5h chip can use the Z.ai monitor API's token quota percentage instead of Anthropic rate_limits. The refresh is detached and cached, so the statusline never waits on the network; non-GLM sessions never poll.
  • Identity row shows model, reasoning effort, tmux pane context, repo, worktree, branch, dirty file count, and PR review state.
  • Agent-active mode: when a subagent is dispatched, the model name dims and a pulsing chip shows the agent name — at-a-glance "my turn is paused".
  • Tmux integration: when running inside tmux, the identity row gains a tmux:session:window.pane chip to disambiguate multiple Claude sessions across panes.
  • TOML configuration: every color, threshold, glyph, and chip toggle is configurable via ~/.config/claudebar/config.toml. Changes recompile automatically on the next render.
  • Graceful degradation: rate-limit bars hide when not on a subscriber tier; PR chip hides without a PR; effort chip hides on models without effort support; worktree marker hides outside worktrees. No placeholder text, no orphan separators.
  • Cross-platform: macOS, Ubuntu/Debian, Arch, Fedora, WSL2 — same bash script, no edits.

Each state at a glance

StateRender
Calm — start of session, low context, clean tree
Mid-session — worktree, dirty tree, PR pending
Caution — yellow zone (60-89%)
Danger — red zone (≥90%) + PR changes requested
Subagent dispatched — model dims, agent chip pulses
PR approved — clean tree, green PR chip
Main working tree — no worktree, no PR, minimal chrome
Tmux integration — tmux:session:window.pane chip

Install

npx @henryavila/claudebar install

This:

  1. Copies the statusline script to ~/.config/claudebar/.
  2. Generates a fully documented config.toml with all defaults (commented out).
  3. Backs up ~/.claude/settings.json with a timestamp.
  4. Patches settings.json to point at the installed script.
  5. Registers the self-heal hooks and a native OS self-heal daemon (see How it works). Add --no-daemon to skip the daemon.
  6. Runs diagnostic checks to confirm everything works.

Send any message in Claude Code (or restart it) — the new statusline renders.

Prerequisites

  • jq and git (the script uses them at runtime)
  • A 256-color terminal (anything modern)
  • A Nerd Font installed and active in your terminal

Don't have a Nerd Font? Install one:

npx @henryavila/claudebar install-font

Defaults to JetBrainsMono. Pass --font FiraCode (or any name from nerd-fonts releases) for a different family.

Diagnostics

npx @henryavila/claudebar doctor

Checks bash, jq, git, 256-color, installed files, settings.json, the self-heal/auto-update hooks, the OS self-heal daemon, and version — reports pass/fail for each.

Configuration

npx @henryavila/claudebar config

Opens ~/.config/claudebar/config.toml in $EDITOR. On save, validates the TOML and recompiles automatically. Changes take effect on the next statusline render (next message or 30-second tick).

The config file is self-documenting — every option is listed with its default, commented out. Uncomment only what you want to change.

What you can configure

SectionControls
[colors]Every color in the statusline (xterm-256 codes, 0-255)
[thresholds]Zone boundaries: warning (green→yellow) and critical (yellow→red)
[chips]Toggle any segment on/off: model, effort, tmux, repo, branch, worktree, dirty, PR, agent, each fuel gauge, countdown text, time marker
[layout]Force compact or full layout, set refresh interval
[glyphs]Override Nerd Font icons with any character
[quota]Enable/disable GLM quota polling and set the cache refresh interval

Example

[colors]
model = 99          # change model color to purple

[thresholds]
warning = 50        # go yellow earlier
critical = 80       # go red earlier

[chips]
tmux = false        # hide tmux chip
countdown = false   # hide countdown text on fuel gauges

[quota]
refresh_interval_minutes = 5  # GLM quota cache TTL; minimum 1

Update

npx @henryavila/claudebar update

Replaces the statusline script and toml-parser with the latest version. Your config.toml is backed up and preserved — new config options are added automatically via migration.

Uninstall

npx @henryavila/claudebar uninstall

Backs up settings.json, removes the statusLine block and hooks, deregisters the OS self-heal daemon (launchd/systemd/cron/profile), and deletes ~/.config/claudebar/.

How it works

Claude Code pipes a JSON object to the script's stdin after every assistant message (debounced 300ms) plus on a 30-second tick. The script:

  1. Parses every needed field in a single jq -r invocation using @sh for shell-safe quoting.
  2. Derives the current git branch and dirty-file count, with a 5-second session-scoped cache to avoid re-shelling git on every message.
  3. If config.toml exists, auto-recompiles config.sh when the TOML is newer (adds <1ms overhead per render).
  4. On GLM endpoints, reads the cached Z.ai 5-hour token quota and spawns a detached refresh when stale; Anthropic and non-GLM sessions skip this path entirely.
  5. Composes two rows: identity_row (top) and fuel_row (bottom), with each chip checking its CHIP_* toggle and owning its preceding separator so absences don't leave orphan glyphs.
  6. Prints ANSI-colored text to stdout. Claude Code displays it below the prompt.

GLM quota monitoring

Claude Code does not expose Anthropic-style rate_limits.five_hour data when it is configured for GLM. claudebar detects GLM from the inherited ANTHROPIC_BASE_URL host (api.z.ai, open.bigmodel.cn, or dev.bigmodel.cn) plus ANTHROPIC_AUTH_TOKEN, then refreshes quota-cache.json in the background by calling the Z.ai monitor endpoint. The token is sent exactly as Claude Code provides it, without adding Bearer.

The rendered statusline always reads the local cache first. If the cache is missing or older than [quota] refresh_interval_minutes, claudebar starts quota-fetch.mjs detached and returns immediately; the next render sees the fresh value. The default TTL is 5 minutes, with a 1-minute minimum.

Disable the GLM quota path:

[quota]
enabled = false

Self-healing

Claude Code can re-persist ~/.claude/settings.json from its in-memory snapshot (e.g. on a TUI toggle), dropping the statusLine block — and sometimes the heal hook entry itself. claudebar recovers on two layers:

  • Hooks (fast path) — a silent SessionStart + UserPromptSubmit hook restores statusLine and re-registers itself, bringing the bar back within one prompt.
  • OS daemon (backstop) — because a rewrite can drop the hook entry too (after which nothing hook-driven ever runs again), a native supervisor re-injects everything from outside Claude Code: launchd (macOS), systemd --user (Linux/WSL), or a cron/~/.profile poll fallback. It watches settings.json and restores full parity (statusLine + both heal hooks + the auto-update hook).

Manage the daemon directly with claudebar daemon [install|uninstall|status|restart]. Opt out with claudebar install --no-daemon or [daemon] enabled = false in config.toml.

See DESIGN.md for the full spec and CHANGELOG.md for version history.

Mobile / compact layout

On narrow terminals or mobile connections, claudebar switches to a 3-row compact layout with 5-pip bars:

✦ Opus 4.7 · HIGH  #4 ⏳
claudebar ›  main ✓
ctx ▰▱▱▱▱  12%  5h ▰▱▱▱▱  18%  7d ▰▰▱▱▱  45%

Automatic detection

When connecting via mosh (e.g., Moshi on iOS), compact layout activates automatically — the script detects mosh-server in the process tree.

Moshi iOS setup: Go to Settings > Integrations > Export ENV and enable MOSHI_CLIENT. This ensures detection even if the process-tree walk is blocked.

Other mobile SSH apps

If you use a different mobile terminal app (Termius, Blink, Prompt, etc.) that connects via plain SSH (no mosh), automatic detection is not possible — the SSH protocol does not expose client identity to the server.

Set the override in your remote shell profile (~/.bashrc, ~/.zshrc, etc.):

export CLAUDEBAR_LAYOUT=compact

Or configure it in config.toml:

[layout]
force = "compact"

Detection priority

PrioritySignalHow to use
1CLAUDEBAR_LAYOUT=compactexport in shell profile or app SSH config
2config.toml [layout] forcenpx @henryavila/claudebar config
3MOSHI_CLIENT=1Enable in Moshi iOS settings
4mosh-server ancestor processAutomatic (mosh connections)
5$COLUMNS < 60Automatic (very narrow terminals)

To force full layout on a mosh session: export CLAUDEBAR_LAYOUT=full.

Testing

npm test                    # Node.js CLI tests + bash tests
npm run test:cli            # Node.js CLI tests only
npm run test:bash           # bash tests only
bash test/perf.sh           # asserts <50ms warm-cache execution
bash test/portability.sh    # checks no GNU-only flags, bash 3.2 compat

Contributing

PRs welcome. Keep:

  • statusline.sh performant (<50 ms warm) — single jq call, cache shell-outs.
  • New visual elements documented in DESIGN.md with a screenshot in docs/screenshots/.
  • TDD discipline — every new function gets a unit test in test/unit/.
  • Cross-platform — ./test/portability.sh must still pass.
  • Zero npm dependencies — CLI uses Node.js stdlib only.

License

MIT — see LICENSE.

Acknowledgements

  • Visual inspiration: the 2-row layout of powerlevel10k. claudebar does not depend on p10k — it works in any shell.
  • Pip-bar aesthetic inspired by Apple Watch / Linear progress indicators.
  • Color palette: Catppuccin Mocha base background.
  • Related community projects: ccstatusline, starship-claude.
Ver o original no GitHub

Bom para

Relacionados