convez.ai
PluginProdutividadeIntermediário
danilchernyshev

Claude Code Statusline de Limites

danilchernyshev/cc-limits-statusline

Monitore limites reais, custos e contexto do Claude Code em uma linha

Ver no GitHub
InicialPluginScore · de 0 a 100

Plugin para Claude Code que exibe em tempo real os limites de plano (janela de 5h e 7d), custo da sessão, uso de contexto e um sinal visual codificado por cores para detectar sobrecarga. Mantém você informado sobre quando está próximo de ativar uso extra (pagamento por overage).

Instalação

$npx convez-ai danilchernyshev/cc-limits-statusline

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.1.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Acompanhar consumo de rate limits durante sessões de desenvolvimento
  • Detectar visualmente quando sobrecarga (extra-usage) está ativa
  • Planejar compactação de contexto antes de atingir limites críticos

Veredito

Ferramenta prática e bem pensada para quem trabalha regularmente com Claude Code — elimina a incerteza sobre limites de taxa e custos de overage. A codificação visual por cores é inteligente e o shell script é transparente, sem dependências pesadas.

README

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

cc-limits-statusline

A Claude Code statusline that shows your real plan limits at a glance — the 5‑hour session window, the 7‑day weekly window, your session cost, context usage, and a colour‑coded extra‑usage signal so you instantly know whether you're about to start paying for overage.

cc-limits-statusline demo

~/dev/myproject [Max 20x] Claude Opus 4.8 │ 5h 42% (3h 12m) │ 7d 18% (5d 4h) │ ctx 31% │ Extra-Usage: ON ● │ 💳 $0.00

What it shows

FieldMeaning
~/dev/myprojectCurrent working directory
[Max 20x]Your subscription plan
Claude Opus 4.8Active model
5h 42% (3h 12m)5‑hour session limit used, and time until it resets
7d 18% (5d 4h)7‑day weekly limit used, and time until it resets
ctx 31%Context window used — colour‑coded by how soon you should /compact (green → yellow → red)
Extra-Usage: ON ●Whether extra usage (paid overage) is enabled on your account (ON/OFF). When ON, a coloured ● status dot follows; when OFF the dot is hidden — see below
💳 $0.00Money, kept last: cost of the current session (paid overage / credits)

All percentages are rounded to whole numbers.

The rate‑limit percentages are colour‑coded: green <80%, yellow 80–99%, red ≥100%.

The ctx percentage uses its own thresholds, keyed to when it pays to run /compact rather than to billing (a full context costs nothing — Claude Code just auto‑compacts it). The colour nudges you to compact at a natural breakpoint first: green <70% (plenty of room), yellow 70–84% (good time to /compact), red ≥85% (compact now — auto‑compact is imminent). Both thresholds are configurable — see Configuration.

The extra‑usage signal

The Extra-Usage: field shows whether extra usage (paid overage) is enabled on your account — ON when it is, OFF when it isn't. When it's ON, a status dot follows whose colour reflects the worst of your two limits (when OFF the dot is hidden, since no overage can start):

SignWhenMeaning
🟢 ●worst limit < 80%Enabled, plenty of headroom — not paying
🟡 ●80–99%Getting close to the limit
🔴 ●100–119%At the limit → paid overage active
🔴 ●●≥ 120% (DOUBLE_AT)Well over the limit, paid overage is active

Why a text ● and not ⚡ or a 🟢 emoji? Emoji like ⚡ are rendered by the terminal in their own fixed colour and ignore ANSI colour codes, so a "coloured lightning bolt" always looks the same yellow. The plain text glyph ● (U+25CF) instead takes its colour from ANSI — so it matches the rest of the line, tracks your terminal theme, and keeps a single‑cell width.

All three thresholds (and which fields show at all) are configurable — see Configuration.

Configuration

The statusline reads an optional config file (~/.config/cc-limits-statusline.conf, override with the CC_STATUSLINE_RC env var). The installer seeds it from config.example.conf if you don't have one; without a file the built-in defaults apply. It's sourced as bash — plain NAME=value lines, no restart needed.

Every setting has a default baked into the script, so the file is entirely optional and safe to trim. A setting you omit, comment out, leave blank (YELLOW_AT=), or set to garbage (RED_AT=abc) falls back to its default rather than breaking the line — thresholds expect a non-negative integer and the SHOW_* flags expect 0 or 1; anything else is ignored.

Colour thresholds

The colour of the worst-of-two limit (and the ●/●● dot) is driven by three percentages:

YELLOW_AT=80    # >= this → 🟡 yellow (getting close)
RED_AT=100      # >= this → 🔴 red    (at the limit, paid overage active)
DOUBLE_AT=120   # >= this → 🔴 ●●     (well over the limit, overage active)

The ctx field has its own pair, keyed to when to /compact (not billing):

CTX_YELLOW_AT=70   # >= this → 🟡 yellow (good time to /compact)
CTX_RED_AT=85      # >= this → 🔴 red    (compact now, auto-compact imminent)

Show / hide fields

Each field can be toggled with 1 (show) / 0 (hide). Hiding one drops its │ separator too:

SHOW_CWD=1      # ~/dev/myproject — current working directory
SHOW_PLAN=1     # [Max 20x]       — subscription plan
SHOW_MODEL=1    # Claude Opus 4.8 — active model
SHOW_5H=1       # 5h 42% (3h 12m) — 5-hour session window
SHOW_7D=1       # 7d 18% (5d 4h)  — 7-day weekly window
SHOW_CTX=1      # ctx 31%         — context window used
SHOW_EXTRA=1    # Extra-Usage: ON ● — overage state + status dot
SHOW_COST=1     # 💳 $0.00        — current-session cost

Requirements

  • Claude Code
  • jq (sudo apt install jq / brew install jq)
  • A POSIX shell (bash)

Install

Option A — install script (any setup)

git clone https://github.com/danilchernyshev/cc-limits-statusline.git
cd cc-limits-statusline
bash install.sh

…or as a one‑liner:

curl -fsSL https://raw.githubusercontent.com/danilchernyshev/cc-limits-statusline/main/install.sh | bash

The installer copies statusline.sh into ~/.claude/ and adds this to your ~/.claude/settings.json (backing it up first):

{
  "statusLine": {
    "type": "command",
    "command": "bash /home/you/.claude/statusline.sh"
  }
}

Reload Claude Code and you're done.

Option B — as a Claude Code plugin (marketplace)

This repo doubles as its own Claude Code marketplace. From inside Claude Code:

/plugin marketplace add danilchernyshev/cc-limits-statusline
/plugin install cc-limits-statusline@cc-limits-statusline

The plugin contributes the statusline via ${CLAUDE_PLUGIN_ROOT}/statusline.sh, so there's nothing to copy by hand. Update later with /plugin marketplace update cc-limits-statusline.

Manual install

  1. Copy statusline.sh anywhere (e.g. ~/.claude/statusline.sh).
  2. chmod +x ~/.claude/statusline.sh
  3. Add the statusLine block above to ~/.claude/settings.json.
  4. (Optional) cp config.example.conf ~/.config/cc-limits-statusline.conf and edit it to tune thresholds or hide fields — see Configuration.

How it works

Claude Code pipes a JSON blob to the statusline command on stdin every time it refreshes. The script reads the live rate_limits, cost, and context_window fields from that JSON, and reads the plan name + extra‑usage flag from the cached config ~/.claude.json. No network calls, no extra state.

The two sources have different freshness. The stdin fields are live per refresh. The plan name is not on stdin — it only exists in ~/.claude.json, which Claude Code rewrites on auth events (login / token refresh / restart), not in real time. You can point the script at a different config with the CC_STATUSLINE_CONFIG environment variable (the test suite uses this).

Plan still shows the old tier after upgrading? That's the cache above. After you upgrade (e.g. Pro → Max) on the web, restart Claude Code so it re‑authenticates and rewrites ~/.claude.json; the statusline then shows the new plan. There is no live plan field to read instead.

Tests

A zero‑dependency test suite (just bash + jq) covers plan parsing, percentage rounding, the extra‑usage dot thresholds, and the layout:

bash tests/run.sh

It feeds fixture JSON to statusline.sh (via CC_STATUSLINE_CONFIG) and asserts against the rendered line, and unit‑tests the pure functions by sourcing the script.

Uninstall

Remove the statusLine key from ~/.claude/settings.json (or restore one of the settings.json.bak.* backups the installer left), and delete ~/.claude/statusline.sh.

License

MIT © 2026 Danil Chernyshev

Ver o original no GitHub

Bom para

Relacionados