The ultimate observability overlay for Claude Pro / Max usage.
Always-on, translucent, and accurate to the digit — know whether you're on schedule for your weekly limit before a surge blindsides you.
Claude's Pro/Max plans meter you against a weekly limit (plus a rolling 5‑hour window). The built‑in usage page tells you a number — but not whether you're pacing to run out early or leaving tokens unspent. Token Planner answers the real question:
At my current burn, do I need to ease off, or can I push harder?
It reads the exact account‑wide number Anthropic reports (the same figure shown at claude.ai/settings/usage and by Claude Code's /usage) and layers pacing, projection, and burn‑rate on top — in a glanceable widget that floats over your editor and gets out of the way when you're not looking at it.
- Exact, account‑wide number. Mirrors Anthropic's own server‑side aggregate across every surface (this machine, other machines, web) — not a local estimate.
- Pace engine. For each limit it shows the on‑pace target (where a steady spender would be), your over/under delta, and a projected‑exhaustion time ("on track to hit 100% by Thu 4pm").
- Live stock-style chart. Tick-by-tick weekly and 5-hour utilization on a zoomable timeline (
1H / 6H / 1D / 1W), auto-scaled like a stock price, with a hover crosshair, gaps where you were away, and the ideal pace line in the weekly view. - Weekly burn tracker. How much of your weekly budget you've burned in the last 15 min / 30 min / 1 hour (persisted across restarts).
- All the buckets. Weekly (all models), the 5‑hour session window, and the Sonnet / Opus weekly caps when present.
- Built to disappear. Translucent, frameless, always‑on‑top; hover‑aware click‑through (ghosts out so your clicks pass through to your editor, solidifies the instant you reach for it); drag anywhere;
Ctrl+Alt+Uto summon/hide; collapse to a tiny watch‑face. - Featherweight. A single Rust/Tauri binary, ~35 MB RAM idle — not a 100 MB+ Electron app.
- Private by design. 100% local. The only network call is to Anthropic's own API, authenticated with the token already on your machine. Nothing is sent anywhere else.
Requires Claude Code installed and logged in on the machine — Token Planner reads your local credential to fetch your own usage. Nothing else leaves your computer.
Builds from source and launches it (and on macOS sets it to start at login). Nothing to download, no Gatekeeper prompt:
curl -fsSL https://raw.githubusercontent.com/HoltYoung/Token-Planner/master/install.sh | bashIt installs Rust for you (and, on macOS, the Xcode Command Line Tools if missing). The first build takes a few minutes; after that it just launches.
Download Token Planner_*_x64-setup.exe from the Releases page and run it. (WebView2 is preinstalled on Windows 11.)
Not comfortable with a terminal? Paste this into Claude Code and let it handle everything:
Set up and run this for me: https://github.com/HoltYoung/Token-Planner
Every release also ships a macOS .dmg (Apple Silicon + Intel) and the Windows installer. The macOS app is unsigned, so on first launch right‑click it → Open (or xattr -dr com.apple.quarantine "/Applications/Token Planner.app"). The one‑command install above avoids this entirely.
Prerequisites: Rust; macOS needs Xcode CLT; Linux needs WebKitGTK (libwebkit2gtk-4.1-dev); Windows needs WebView2 (preinstalled on Win 11).
cargo build --release --manifest-path src-tauri/Cargo.toml # overlay
cargo build --release --bin tokplan # CLI| Action | How |
|---|---|
| Move it | Click‑and‑hold anywhere, drag |
| Expand / collapse | Click the ▾ / ▴ |
| Hide / show | Ctrl+Alt+U |
| Interact | Just point at it — it solidifies on hover, ghosts when you leave |
tokplan # one-shot readout
tokplan --watch # live terminal dashboard (default 120s poll)
tokplan --watch -i 180 # custom poll interval (min 30s)
tokplan --json # raw usage JSONClaude Code credential (file on Win/Linux · Keychain on macOS) ─┐
▼
GET https://api.anthropic.com/api/oauth/usage
│ (authoritative %)
┌─────────────────────────────────────┘
▼
token_planner (Rust engine): parse buckets → pace math → burn history
│
┌───────────┴───────────┐
▼ ▼
tokplan (CLI) Tauri overlay (watch-face)
The endpoint returns a pre‑weighted utilization percentage per bucket — Anthropic does all the model/cache weighting server‑side, so the displayed number is authoritative and we never re‑derive it from local logs. The engine adds a rolling history of samples to compute burn‑rate and the trend, polls conservatively with exponential back‑off, and fails soft to the last good value (shown with a "stale" badge) if a fetch fails.
Note / fair use. This reuses your own Claude credential to read your own usage, read‑only, at a polite cadence. The usage endpoint is undocumented and Anthropic's consumer terms scope plan tokens to Claude Code / claude.ai, so treat this as a personal, local tool. Endpoint, headers, and User‑Agent are config‑driven (
ANTHROPIC_BASE_URL,TOKPLAN_USER_AGENT) so it can be pointed elsewhere or disabled.
| Path | What |
|---|---|
src/lib.rs |
token_planner engine — credentials, fetch, tolerant parsing, pace math (UI‑free) |
src/main.rs |
tokplan CLI — terminal renderer + watch loop |
src-tauri/ |
Tauri v2 overlay — polls the engine, renders the watch‑face |
ui/ |
Static frontend (no bundler) — canvas trend chart + donut |
- macOS / Linux builds (the engine is already cross‑platform)
- System‑tray mode + threshold notifications
- Sub‑poll interpolation for a smoother live feel
- Per‑project/model attribution ("where did my week go") from local Claude Code logs
MIT — see LICENSE.