claude-limit-statusline

A Claude Code status line that shows your real subscription limits — the 5‑hour session window and the 7‑day weekly window — and when they reset (local time by default, or a countdown — your pick).

📦 npm · 🔗 GitHub

🤖 Opus 4.8 | 🧠 42k (4%) | 🕔 Session 17% · resets at 20:16 | 📅 Week 10%

That's the default (medium). Pick the size that fits your terminal — from full (everything, both reset times) down to bare (just the two percentages).

Unlike tools that estimate the 5‑hour block from local logs, this reads the official rate_limits payload that Claude Code provides on stdin — the same numbers you see when you run /usage. No guessing, no rounding to the hour.

Who is this for?

This shows the subscription rate limits that Anthropic exposes only to Claude.ai Pro/Max users. If you use the pay‑as‑you‑go API, the rate_limits field is not present — you probably want a cost tracker like ccusage instead.

| | Pro/Max subscription | Pay‑as‑you‑go API | | --- | --- | --- | | rate_limits in status line | ✅ yes | ❌ no | | What this tool shows | 5h + 7d limit % and reset | — |

Install

npm install -g claude-limit-statusline
cc-limits --install

That's it. --install writes the statusLine entry into ~/.claude/settings.json for you (merging, never clobbering your other settings). Then open a new Claude Code session and send one message — rate_limits populates after the first API response.

Want a different size? Pass your display options straight through:

cc-limits --install --size=compact

To remove it again:

cc-limits --uninstall

Why --install instead of editing by hand? It records an absolute node + script path, so it works even under nvm/Volta where a globally installed command isn't on the PATH of the non‑login shell Claude Code uses for the status line.

Upgrading from 0.4.x? Resets now show the local time by default (resets at 20:16) instead of a countdown. Prefer the old look? Re-run cc-limits --install --reset-style=countdown (or both).

Upgrading from 0.3.x / 0.2.x? The old adaptive‑width behavior is gone — replaced by fixed sizes (default medium). Re‑run cc-limits --install (optionally with --size=…) to refresh the baked‑in command; any leftover --width / --no-adapt flags are now ignored. The session icon also changed from ⏳ to 🕔.

Add this to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "cc-limits"
  }
}

If the bar stays blank (nvm/Volta PATH issue), use absolute paths instead — "command": "/path/to/node /path/to/cli.js" (find them with which node and npm root -g), which is exactly what cc-limits --install does automatically.

Output

| Segment | Meaning | Source | | --- | --- | --- | | 🤖 model | Active model | local | | 🧠 42k (4%) | Tokens in the current context window | local | | 🕔 Session 17% · resets at 23:12 | Real 5‑hour limit used (+ reset) | server | | 📅 Week 10% · resets at Jun 03 19:54 | Real 7‑day limit used (+ reset) | server |

The percentage is your "how close am I to the limit" gauge. Subscription limits are dynamic, so Anthropic does not expose a fixed token cap — only a percentage, which is exactly what this surfaces.

Before the first API response (and right after /compact) the session segment shows 🕔 Session -- until fresh data arrives.

Sizes

Claude Code shows the status line on a single line and truncates anything past the terminal width. So instead of guessing, you pick the size that fits — set it once with --size (or CC_LIMITS_SIZE). The default is medium.

full     🤖 Opus 4.8 (1M context) | 🧠 42k (4%) | 🕔 Session 17% · resets at 23:12 | 📅 Week 10% · resets at Jun 03 19:54
medium   🤖 Opus 4.8 | 🧠 42k (4%) | 🕔 Session 17% · resets at 23:12 | 📅 Week 10%
compact  🤖 Opus 4.8 | 🧠 42k (4%) | 🕔 Session 17% | 📅 Week 10%
mini     🤖 Opus 4.8 | 🧠 42k | 🕔 S 17% | 📅 W 10%
bare     🕔 S 17% | 📅 W 10%

| Size | Shows | | --- | --- | | full | Model (with context length), tokens + %, both limits with reset times | | medium | Model, tokens + %, session reset time, both percentages (default) | | compact | Model, tokens + %, both percentages — no resets | | mini | Model, tokens, short labels | | bare | Just the two limits |

cc-limits --install --size=compact

You can still fine‑tune any size with --segments, --reset, and --reset-style below.

Configuration

Pick which segments to show (and their order). The four segments are model, context, session, week.

// Only the two limits, nothing else:
"command": "cc-limits --segments=session,week"

// Everything except the context tokens:
"command": "cc-limits --no-context"

Cap which resets a size may show (this can hide a reset, never add one):

"command": "cc-limits --size=full --reset=session"  // full, but no week reset
"command": "cc-limits --no-reset"                   // just percentages, no resets
"command": "cc-limits --reset=auto"                 // resets appear only once a
                                                    // limit hits the warn % (70)

Reset display style

By default a reset shows the local wall-clock time (resets at 20:16 — the weekly one includes the date). Prefer a countdown? Pick a style with --reset-style (it re-formats the resets a size already shows — it never adds one, so your chosen size keeps fitting):

--reset-style=clock       🕔 Session 17% · resets at 20:16              ← default
--reset-style=countdown   🕔 Session 17% · resets in 0h47m
--reset-style=both        🕔 Session 17% · resets in 0h47m (20:16)     (clock part only on full)

Prefer 12-hour times? Add --clock=12 (resets at 8:16pm). When a reset time has already passed, all styles show resets now.

cc-limits --install --size=medium --reset-style=countdown

Flags

| Flag | Description | | --- | --- | | --size=full\|medium\|compact\|mini\|bare | How much detail to show (default medium) | | --segments=a,b,c | Allowlist + order. Subset of model,context,session,week | | --no-<segment> | Hide one segment (e.g. --no-context). Repeatable | | --reset=both\|session\|week\|none\|auto | Cap which resets may show (default both). auto = only at/above the warn % | | --no-reset | Shorthand for --reset=none | | --reset-style=clock\|countdown\|both | Local time, countdown, or both (default clock) | | --clock=24\|12 | Clock format for reset times (default 24) | | --no-color | Disable ANSI colors | | --demo | Print a sample line (no stdin needed) | | -h, --help | Show help |

Environment variables

Equivalent to the flags, handy if you don't want to edit the command string:

| Env var | Default | Description | | --- | --- | --- | | CC_LIMITS_SIZE | medium | full / medium / compact / mini / bare | | CC_LIMITS_SEGMENTS | model,context,session,week | Segments + order | | CC_LIMITS_RESET | both | both / session / week / none / auto | | CC_LIMITS_RESET_STYLE | clock | clock / countdown / both | | CC_LIMITS_CLOCK | 24 | 24 / 12 hour clock for reset times | | CC_LIMITS_WARN | 70 | % at/above which a limit turns yellow | | CC_LIMITS_CRIT | 90 | % at/above which a limit turns red | | CC_LIMITS_SEP | " \| " | Separator between segments | | NO_COLOR | — | Set to disable ANSI colors |

cc-limits --demo
cc-limits --size=compact --demo

How it works

Claude Code runs your status-line command on every update and pipes a JSON status-line payload to stdin. This program parses it and reads:

• rate_limits.five_hour.used_percentage / .resets_at
• rate_limits.seven_day.used_percentage / .resets_at
• context_window.* for the token/context segment

resets_at is Unix epoch seconds; reset times and countdowns are computed from it locally. Everything runs with zero dependencies for fast startup.

License

MIT