ccmon · A live dashboard for Claude Code and Codex

Coding agents keep a diary. Every response Claude Code gives you lands in a transcript under ~/.claude; every turn Codex CLI takes lands in a rollout under ~/.codex. Both record exact token counts. ccmon reads both diaries and turns them 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.

Two tools, one dashboard, side by side — each with its own accounts, plans and rate limits.

No API key. No setup. No telemetry. ccmon finds your data on its own, indexes weeks of history in a few seconds, then follows along. New responses appear within a second.

A scripted tour across a synthetic multi-account dataset, recorded with npm run promo.

Start

Discovery needs no configuration. Claude Code is read from ~/.claude/projects/, any sibling ~/.claude-<name> root from a multi-account setup, and $CLAUDE_CONFIG_DIR. Codex is read from ${CODEX_HOME:-~/.codex}/sessions/ and archived_sessions/.

Pulse

The page you leave open. Today's spend, the current five-hour block, live plan limits for every account, and a feed that ticks as you work.

Zoom

Subscription limits run in five-hour billing windows, and 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.

Your limits, live — and read two different ways

For Claude Code, ccmon reads the same numbers the /usage screen reads, using the login Claude Code already stored, refreshed 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.

For Codex, there is no endpoint to poll — and none is needed. Codex writes its own rate limits into the session log on every turn, so ccmon reads them with no network call and no credentials at all.

Analytics

Economics, ROI and forecasting on one page — plus the daily model stack and cumulative burn.

Zoom

• Plan value — what this month would have cost on the API, next to what the subscription costs. The multiple tends to be persuasive.
• Cache economics — 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 — every request re-priced onto another model, entry by entry. An all-Sonnet month and an all-Haiku month, next to what you actually spent.
• The month, projected — with an honest uncertainty band, plus weekday rhythm, week-over-week, spike days, streaks and records.

Projects

Spend per repo in four layouts — split, grid, table, and a force-directed knowledge graph. Every project gets a sparkline, today, seven days, all time, cache hit rate and 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

Accounts

Every login, plan and rate limit side by side, across both CLIs — and how many sessions each one has running right now.

Zoom

When one account is about to cap while another sits idle, ccmon says so and hands you the exact claude-cross-resume command to pick up where you left off on the account that still has room. Codex gets the same treatment via codex-cross-resume, and a setup wizard writes the per-shell claude-* and codex-* wrappers for you.

The 3D canvas

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

Zoom

The AI advisor

Ask questions about your own usage in plain language. It sends aggregates only — never transcripts — reusing the login already on disk, and Ctrl+J opens it as a drawer from any page.

Zoom

Make it yours

Seventeen themes, dracula by default, 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. Ctrl+P blanks every dollar figure on screen — for screen-sharing, and it masks in the tray and the CLI statusline too.

Zoom

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

{
  "claudeDirs": ["/extra/claude/root"],
  "modelAliases": { "arn:aws:bedrock:.*:profile/abc": "opus (bedrock)" },
  "pricing": {
    "my-custom-model": { "in": 5, "out": 25, "w5m": 6.25, "w1h": 10, "read": 0.5 }
  }
}

claudeDirs adds data roots beyond the defaults. pricing takes per-MTok overrides — case-insensitive regexes that always win, reaching tier rates and context limits, not just the five base rates. modelAliases and projectAliases rename things for display only, never before pricing or grouping.

The command line

Every build ships a headless CLI that runs the whole pipeline under plain Node — same data, same settings, no Electron, no window.

ccmon json --range 30d --section totals,models --pretty
ccmon json | jq '.totals.cost'
ccmon csv days --since 20260101 > days.csv
ccmon statusline

statusline is designed to answer inside a shell prompt, which is a different problem from filling a dashboard: it windows discovery by file mtime and returns in about 0.9 s where a full scan takes 7 s. json and csv never window — a partial index that silently understates lifetime totals is worse than a slow one — and neither is ever masked by privacy mode, because blanking numbers in machine output corrupts it rather than protecting it.

Both tools, priced properly

Counting Claude tokens correctly is a solved problem, and ccmon proves it against ccusage. Codex was the interesting one.

Fitting Codex is also what proved the architecture. A Codex usage line is not self-describing: its model comes from an earlier context event and its speed tier from an earlier settings event, so a line read in isolation cannot be priced at all. No amount of designing against one format would have surfaced that.

Can you trust the numbers?

Yes, and you can check.

867 unit tests pin the parsing, pricing, block, forecast, account and shell-integration logic, and CI runs them on Linux, macOS and Windows on every push. That three-OS matrix isn't ceremony: the keychain reader shells out to macOS security(1) and the account setup emits PowerShell, and both used to be exercised only against mocks on Linux.

Where a number is a heuristic, the panel says so — every analysis carries a small "why?" button explaining exactly how it is computed and where it stops being reliable.

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 six deliberate exceptions you can see and control in settings. All are read-only, all keep the last good value on failure, and none of them send your transcripts anywhere.

Codex adds none of them. Its rate limits, plan and identity are all read from files it already wrote to your disk — no OpenAI request is ever made.

Flip pricing to offline and ccmon runs entirely from bundled snapshots. Nothing is written anywhere except your own disk. No telemetry, no analytics, no crash reporting.

Under the hood

ccmon is two processes with one contract between them. A pure Node service layer inside the Electron main process turns log files into an immutable snapshot. A sandboxed React renderer draws whatever snapshot arrives. The renderer holds no business logic — which is also why the same service layer runs headless as a CLI.

The decisions that shaped it:

• Services never import Electron. That single rule makes the whole pipeline runnable headless and unit-testable against real data — and it is what let the CLI exist at all. Twenty-six services, zero GUI required. A service needing an Electron API takes it injected rather than importing it.
• An adapter owns what is format-specific; the watcher owns what isn't. Tailing, offsets, per-file state and dedupe live in the watcher. detectRoots, owns and parseLine live in the adapter. Supporting a new coding CLI is appending to a registry.
• Tail, don't rescan. Per-file byte offsets plus a partial-line remainder make every read O(appended bytes). A byte-level prefilter skips the JSON parse for lines that cannot carry data, which is 41% of the parse path.
• Best-wins dedupe. Streaming chunks repeat a 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. Every derived number stays consistent by construction, with per-entry dollars resolved exactly once. ~610 ms at 110k entries, on a debounce.
• 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.
• One day-bucketing function. Every date key, "today", range and heatmap goes through it, driven by a timezone setting. Changing the zone re-stamps history in one pass without a rescan.
• 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

Get it