ccpredict

Forecast when you'll hit your Claude Code usage limits — and toggle individual sessions on/off to steer the prediction before the wall.

ccpredict is a terminal UI that reads Anthropic's own /api/oauth/usage endpoint (the same one powering Claude Code's Account & Usage modal) for ground-truth percentages, tails your local session JSONLs in real time for per-session burn rate, and combines them into a live forecast: "at this pace your session limit hits in 1h 47m, weekly holds until reset."

The unique feature: every running claude process shows up as a checkbox. Hit [space] and the forecast instantly recomputes without that session's burn rate. When you're headed for a breach, ccpredict tells you which specific session to close to survive: "toggle off rna_decontam → weekly survives with 2d 4h to spare."

Install

npx @elliotxie/ccpredict          # zero-install, recommended
# or
npm i -g @elliotxie/ccpredict
ccpredict

Requires Node.js ≥ 20. Reads your existing Claude Code OAuth token from ~/.claude/.credentials.json — no separate login flow.

What it shows

╭ ccpredict · Claude Max 20x · [email protected] ───────── synced 2s ago · 22:14 ╮

  ████████░░░░░░░░░░░░░░░░   SESSION (5hr)     18%  · resets in 3h 02m
  ██████████████░░░░░░░░░░   WEEKLY  (7d)      16%  · resets in 6d 04h
  ░░░░░░░░░░░░░░░░░░░░░░░░   WEEKLY SONNET      0%  · resets in 6d 04h

  ⚡ At current pace → session limit in  14h 02m
                       weekly limit  in  20d 05h

  ✓ session — survives this window before reset
  ✓ weekly  — plenty of runway, ship something

  ▸ tip: hit [space] on a session below to see the forecast without it.

    burn: 705k weighted tok/min

  Burn rate · last 60 min · weighted tokens/min
  ▂▃▂▅▇█▇▆▄▃▂▃▅▇█▇▅▃▂▂▁▁▂▂▄▅▆▆▇▆▅▄▂▃▃▅▇█▇▆▅▃

  Active sessions              (space: toggle · ↑↓: nav · a: enable all)
    [x] autosearch            pid 41804  opus    1.2k/min
    [x] ccpredict             pid 28000  opus    0.4k/min
    [ ] voice2text            pid 30408  opus    idle · 41m

  [r] sync   [space] toggle   [a] enable all   [q] quit

Why another one?

There are good tools already:

• ccusage — historical tables + cost accounting. Use it for "what did I spend last month?"
• Claude-Code-Usage-Monitor — the incumbent real-time TUI. Use it for "where am I right now?"

ccpredict focuses on the future, not the past or present:

| | ccusage | Claude-Monitor | ccpredict | |------------------------------------------|:---------:|:--------------:|:-------------:| | Calls Anthropic's /api/oauth/usage for real server % | — | — | ✓ | | Interactive per-session toggles (counterfactual what-if) | — | — | ✓ | | Self-calibrating tokens/% via two-poll EWMA | — | — | ✓ | | Weekly ETA vs reset verdict ("runs out 2d before reset") | — | partial | ✓ | | Auto-suggests which session to disable to survive | — | — | ✓ | | Historical daily/monthly tables | ✓ | ✓ | — | | Per-model $ cost breakdown | ✓ | ✓ | — | | npx/zero-install on Windows | — | — | ✓ |

The three tools are complementary. ccpredict is what you open when you're about to start a long session and want to know "can I actually afford this?"

How it works

Two data sources, two update cadences:

1. Server truth — every 5 minutes (60s floor, exponential backoff on 429). GET https://api.anthropic.com/api/oauth/usage with the OAuth token from ~/.claude/.credentials.json and the anthropic-beta: oauth-2025-04-20 header. Returns {session, weekly, weekly_sonnet} utilization percentages and reset timestamps. This is the ground-truth anchor.

2. Local burn rate — real-time, event-driven. chokidar watches ~/.claude/projects/**/*.jsonl. Every assistant message Claude Code writes carries a message.usage object with input_tokens / cache_creation_input_tokens / cache_read_input_tokens / output_tokens and the model name. We tail the new bytes and compute weighted tokens/min per session over a 15-minute trailing window.

3. The forecast is a pure function of the two:

sessionPct(t) = anchor.session.utilization
              + (Σ enabled burnRate) · (t − anchor.polledAt) / tokensPerPct

tokensPerPct ← EWMA of Δ(cumulative tokens) / Δ(server %)  across successive polls

Seeded on first poll by your 5-hour backfill, then self-calibrates as more polls arrive. Toggling a session simply removes its burnRate from the sum — no server call, no recalibration, just instant counterfactual math.

Rate-limit safety

Anthropic aggressively rate-limits /api/oauth/usage (issue #31637, #31021). ccpredict is designed to stay well under:

• Default poll interval: 300 seconds (~12 requests/hour)
• Manual [r] refresh: respects a hard 60-second floor
• On 429: exponential backoff up to 30 min, UI keeps projecting from the last known anchor
• On auth failure: clear "run claude login" message

Between polls, the gauges still move — they're being projected forward from the last server reading using your live local burn rate.

What's counted

Because the session/weekly percentages come from /api/oauth/usage, the gauges reflect all your Claude usage against the cap, including claude.ai web chat and CoWorker — not just Claude Code. ccpredict can only attribute per-session burn rate to processes whose JSONL it can tail (i.e. local claude CLI processes), but the bucket totals are account-wide.

Subagents launched via the Task tool run as their own claude processes and write their own JSONL under ~/.claude/projects/. Their burn is counted toward the same caps and shows up in the session list as a separate row, not silently rolled into the parent.

Keys

| Key | Action | |------------|---------------------------------------------| | ↑ / ↓ | Navigate session list | | space | Toggle the highlighted session on/off | | a | Re-enable all sessions | | r | Manually sync with /api/oauth/usage | | q / Ctrl+C | Quit |

Flags

ccpredict [options]

  --poll-seconds <n>    Override poll interval (>=60). Default 300.
  --tier <tier>         Override plan tier if the server-reported label is wrong.
                        Values: pro | max-5x | max-20x
                        (persists to ~/.ccpredict/config.json)
  --alt-screen          Run in alternate-screen mode (htop-style; hides scrollback).
                        Off by default so your scrollback is preserved.
  --once, --json        Print a one-shot JSON snapshot and exit. Good for scripts.

Example — pipe the JSON snapshot into jq:

ccpredict --json | jq '.poll'

Config

~/.ccpredict/config.json (auto-created on first --tier flag):

{
  "pollSeconds": 300,
  "burnWindowMinutes": 15,
  "sparklineMinutes": 60,
  "tierOverride": "default_claude_max"
}

Environment variables

| Variable | Effect | |---|---| | CLAUDE_CONFIG_DIR | Override the Claude Code root directory (where .credentials.json and projects/ live). Same env var Claude Code itself respects. Useful for multi-account setups. | | CLAUDE_HOME | Legacy override, same effect. CLAUDE_CONFIG_DIR takes precedence if both are set. | | CCPREDICT_HOME | Override the ccpredict config directory (defaults to ~/.ccpredict). |

Pricing override

If Anthropic ships a model whose name our weighting doesn't recognize, drop a ~/.ccpredict/pricing.json to override factors without waiting for a release. Shallow-merges over defaults; provide only the keys you want to replace:

{
  "models": [
    { "match": "opus", "factor": 5.0 },
    { "match": "haiku", "factor": 0.27 },
    { "match": "your-new-model", "factor": 1.5 }
  ]
}

Privacy

• No telemetry. ccpredict makes exactly one network call: to api.anthropic.com, using your OAuth token, for your usage percentages.
• Credentials never leave your machine. We read ~/.claude/.credentials.json locally and send the access token only in the Authorization header to Anthropic. No third-party services.
• JSONL reads are local. Session token counts are computed from files Claude Code already wrote to disk on your machine.

Development

pnpm install
pnpm dev        # runs src/cli.tsx via tsx
pnpm test       # vitest
pnpm build      # tsup → dist/cli.js

Credits

• ink — React for the terminal.
• chokidar — cross-platform file watching.
• ccusage and Claude-Code-Usage-Monitor for establishing the category.

License

MIT.