A local, terminal-styled dashboard for Claude Code token usage and cost — with estimated session/weekly reset countdowns.
Reads your existing Claude Code session logs (~/.claude/projects/**/*.jsonl) directly off disk. No API key, no cloud account, no VPS, and nothing runs in the background — it's a foreground process you start when you want to look, and stop with Ctrl+C.
Node.js 22.6+ (needs native TypeScript support and node:sqlite, both built in — no npm install required).
git clone https://github.com/laghab/claude-watch.git
cd claude-watch
node bin/claude-watch.tsThis starts a server on 127.0.0.1 (default port 4317) and opens the dashboard in your default browser. On first run it does a one-time backfill of your existing Claude Code history; after that it only ingests new log lines.
Stop it with Ctrl+C — this closes the local database connection and releases the port. No daemon, no systemd/launchd unit, nothing left running.
Write this to ~/.local/share/applications/claude-watch.desktop, replacing /path/to/claude-watch with wherever you cloned it:
[Desktop Entry]
Type=Application
Name=Claude Watch
Comment=Local dashboard for Claude Code token usage and cost
Exec=/usr/bin/node /path/to/claude-watch/bin/claude-watch.ts
Path=/path/to/claude-watch
Icon=utilities-system-monitor
Terminal=true
Categories=Development;
StartupNotify=trueTerminal=true is deliberate: the terminal window is the running process, so closing it stops the server. Same "no background service" behavior as launching by hand.
- Overview cards — today / current session window / current weekly window / all-time, each with tokens and estimated $ cost. Click a card to copy its numbers to the clipboard.
- Cache efficiency meter — the share of your cacheable tokens actually served from cache instead of rewritten. Low efficiency is a real "you're paying the cache-write premium for nothing" signal — worth checking if a project's cost looks high.
- Budget meters (optional, see Configuration) — a % against a token budget you set yourself.
- Daily usage chart — stacked by model, hover any segment for exact tokens/cost. Switch the range between 7/14/30/90 days.
- Breakdown — by model or by project. Click any column header to sort; export the current view to CSV.
- Sessions — one row per Claude Code session; click a row to expand into every individual message in that session (timestamp, model, input/output/cache-read tokens, cost, plus a copy-session-id button). Filter by project or session id, sort by any column, or export to CSV.
- History — daily totals table, exportable to CSV.
- Panels are collapsible — click a panel's title to fold it out of the way.
- Themes — cycle between the default green terminal look, amber, blue, and monochrome via the theme button (persists across reloads via
localStorage). - Manual refresh — the refresh button (or
r) re-polls immediately instead of waiting for the next 4s tick; a "last updated" timestamp sits next to it.
r refresh · t cycle theme · / focus the session filter · m/p switch breakdown grouping · 1-4 switch chart range · ? toggle this list · Esc close a dialog or clear the filter. Click the ? button in the top bar for the same list in-app.
A config file is created at ~/.claude-watch/config.json on first run:
{
"sessionWindowHours": 5,
"weeklyWindowDays": 7,
"port": 4317,
"sessionTokenBudget": null,
"weeklyTokenBudget": null
}sessionWindowHours / weeklyWindowDays control the rolling windows used to estimate your session and weekly usage-limit resets. These are inferred from your own usage timestamps, not read from your Anthropic account — there's no local or API signal for the authoritative reset time — so adjust them if your plan's actual limits differ from the defaults.
Anthropic doesn't expose the exact percentage the claude.ai website shows anywhere via API for personal accounts — the only programmatic access (the Admin/Usage Cost API) explicitly requires an actual Console organization with API billing, not a personal Pro/Max subscription. So this dashboard can't replicate that number exactly.
What it can do: if you set sessionTokenBudget and/or weeklyTokenBudget (a token count you pick — e.g. roughly what you've burned historically before getting rate-limited), the session/weekly cards show a progress-bar % against your own number. It's clearly labeled as a self-configured estimate, not an official Anthropic figure. Leave them null (the default) to hide the meters entirely.
Everything lives in one plain SQLite file: ~/.claude-watch/cache.sqlite, table raw_usage (one row per assistant message: timestamp, session, project, model, and every token category). If the Sessions drill-down in the dashboard isn't enough, open it directly with sqlite3 ~/.claude-watch/cache.sqlite or any SQLite browser and query it however you want — nothing is locked away in a proprietary format.
Cost figures come from a versioned pricing table baked into src/pricing.ts (last updated: see the date shown in the dashboard footer). If a model you're using isn't in the table, its tokens still show up but its cost is marked "unpriced" rather than guessed. To add or correct a price without editing code, create ~/.claude-watch/pricing.json:
{
"some-new-model-id": { "input": 3, "output": 15, "cacheWrite5m": 3.75, "cacheWrite1h": 6, "cacheRead": 0.3 }
}(All values are USD per million tokens.) Entries here override the built-in table.
Everything this tool owns lives in one place:
rm -rf ~/.claude-watchThat deletes the local cache database and config. Then remove the cloned repo (and the .desktop file, if you made one). Nothing else on your system is touched — all access to ~/.claude/projects is read-only, and there's no service, scheduled task, or system-level configuration to clean up.
- All totals are this machine only. If you use Claude Code on multiple devices, this won't reflect usage from the others.
- Session/weekly reset countdowns are estimates, not authoritative values from your Anthropic account.