ccmon · A live dashboard for Claude Code

Claude Code keeps a diary. Every response it gives you lands in a transcript file under ~/.claude, with exact token counts attached. ccmon reads that diary and turns it into numbers you can act on. What today cost. How hot the five-hour window is running. Which model is eating the budget. When your limits reset.

No API key. No setup. No telemetry. It finds ~/.claude on its own, indexes weeks of history in a few seconds, then follows along. New responses appear within a second.

Real footage from ~/.claude, recorded with npm run promo.

Start

Your limits, live

The /usage screen in Claude Code knows your real limits. ccmon reads the same endpoint, with the login Claude Code already stored, and shows session, weekly, and per-model gauges that refresh every sixty seconds.

Then it goes one step further. It learns your pace and forecasts the cap. "Caps around Friday 1 AM at this pace" is more useful than a percentage.

Zoom

The five-hour block

Subscription limits run in five-hour billing windows. ccmon treats the active one as a first-class object: burn rate, countdown, and a projection of where the block lands by its end.

Behind it sit thirty days of block history — idle gaps included — and a utilization histogram that shows whether you fill your windows or graze them.

Zoom

Where the money goes

The activity view is the calendar of it. Daily cost by model, cumulative spend, weekly and monthly rollups, streaks, spike days, record days.

Zoom

The models view is the economics of it. Prompt caching gets a full accounting — what you paid, what the same traffic would have cost uncached, and the hit rate that separates the two. Including the cost of walking away: leave a session longer than the cache TTL and your next message re-writes context you already paid for. ccmon counts exactly what that habit costs.

What-if re-prices every request onto another model, entry by entry. An all-Sonnet month and an all-Haiku month, next to what you actually spent.

Zoom

The month, projected

Insights turns the history forward. A month-end projection with an honest uncertainty band. Plan value — what this month would have cost on the API, next to what the subscription costs. The multiple tends to be persuasive. Weekday rhythm, week-over-week, model economics, records.

Zoom

Projects, sessions, subagents

Every project gets a card: sparkline, today, seven days, all time, cache hit rate, last active. Subagent spend is tracked separately, so a workflow that fans out twenty agents shows up as exactly that, not as one mysterious session.

Zoom

The 3D view

Nine ways to slice your usage. Seven ways to draw each one. Terrain, ridges, surfaces, scatter, a cumulative spend trail that snakes through the calendar. It is mostly for joy, and that's fine.

Make it yours

Seventeen themes, from lofi warm charcoal to daylight. Every theme is the same set of CSS tokens, so adding one is adding an object. Costs display in any of 160+ currencies, the top ten crypto included, with rates refreshed hourly.

Zoom

Power users get a config file at ~/.config/ccmon/config.json:

{
  "claudeDirs": ["/extra/claude/root"],
  "pricing": {
    "my-custom-model": { "in": 5, "out": 25, "w5m": 6.25, "w1h": 10, "read": 0.5 }
  }
}

claudeDirs adds data roots beyond the defaults, with per-account scoping for multi-account setups. pricing takes per-MTok overrides; keys are case-insensitive regexes and always win.

Can you trust the numbers?

Yes, and you can check.

58 unit tests pin the parsing, pricing, block, and forecast math, and CI runs them on every push. Where a number is a heuristic, the panel says so — every analysis carries a small "why?" button that explains exactly how it is computed.

Costs are API list prices. On a Pro or Max subscription, read them as API-equivalent value rather than an invoice.

Private by construction

Everything stays on your machine, with three deliberate exceptions you can see and control in settings:

• Model prices refresh daily from the LiteLLM catalog. Cached, optional.
• Plan limits come from Anthropic's usage endpoint. Read-only, using the login Claude Code already stored.
• Currency rates refresh hourly from open.er-api.com and CoinGecko.

Flip pricing to offline and ccmon runs entirely from bundled snapshots. Nothing is written anywhere except your own disk.

Under the hood

ccmon is two processes with one contract between them. A pure Node service layer inside the Electron main process turns transcript files into an immutable snapshot. A sandboxed React renderer draws whatever snapshot arrives. The renderer holds no business logic.

The decisions that shaped it:

• Services never import Electron. That single rule makes the whole pipeline runnable headless (npm run smoke) and unit-testable against real data. Thirteen services, zero GUI required.
• Tail, don't rescan. Per-file byte offsets plus a partial-line remainder make every read O(appended bytes). Files untouched for seven days are indexed but not watched, so inotify usage tracks recent activity.
• Best-wins dedupe. Streaming chunks repeat a messageId:requestId key with cumulative usage; the largest wins. Subagent usage mirrored into parent transcripts keeps one copy. This is the rule that buys ccusage parity.
• Full recompute over incremental aggregation. ~45k entries reduce in ~200 ms on a 250 ms debounce. Every derived number stays consistent by construction.
• Entries cost at the rates of their day. A dated pricing archive records every catalog change, so old months keep their old prices instead of silently re-pricing.
• Snapshot-push IPC. One store, selector subscriptions, no fetch waterfalls. The renderer renders; it does not compute.
• Locked-down renderer. Context isolation, sandbox on, no Node integration, strict CSP injected at build time. The renderer can only call what the preload exposes.

By the numbers

Why it is here

zy is systems engineering in C. ccmon is the same discipline pointed at product engineering in TypeScript: a data pipeline that has to be provably correct, an architecture that keeps it testable, and a UI that makes the numbers feel obvious.

It is also the rare portfolio piece I open every day. I built it to answer my own question — what is this costing me — and kept it because the answer kept being interesting.