Meter your Claude Code burn.
Always on.

WHAT IS THIS

It just reads the logs. No API key, no setup.

Claude Code already writes every session to ~/.claude/projects/**/*.jsonl. ctm tails those logs and aggregates the usage of each assistant message. It never touches the sessions being measured — zero observer effect.

Claude Code's logs write the same message multiple times (~1.7× inflation, measured); ctm dedupes on message.id + requestId. Cache writes (5-minute and 1-hour) and cache reads are priced at their real rates (1.25× / 2.0× / 0.1×).

DEMO 01 — TASKBAR

When the aquarium fills up, take a break.

CtmMonitor is a small always-on-taskbar window. It draws your 5-hour limit (front, blue) and weekly limit (back, purple) as a two-layer aquarium, and every burst of consumption floats up as a +N particle tagged with the project that caused it. Drag the window and the water sloshes.

Click to cycle display units (Auto / K / M / RAW) and layouts. Right-click → "Start with Windows" to keep it resident.

DEMO 02 — LIVE

Are we burning right now — and how long until the wall?

The CLI monitor, running in your terminal. Refreshes every second.

ctm auto-detects the 5-hour blocks that rate limits actually operate on, and shows a progress bar, burn rate (tok/min) and a projection at block end. The last 60 minutes render as a sparkline, so you can see exactly when the fire happened.

Refreshes every second. 1–6 switch views, r rescans, q quits.

DEMO 03 — VIEWS

Six angles. One keystroke apart.

By day, by model, by project, by session, by 5-hour block. "How much did yesterday cost?" "Which project is eating the budget?" "Which sessions are alive right now?" — instant answers.

DEMO 04 — SUB-MONITOR

A dedicated gauge on your desk.

Use an M5Stack ATOMS3R (128×128 IPS, IMU) as a display-only sub-monitor. CtmMonitor streams state over USB every 200ms; the device renders the two-layer aquarium and spring counters at 30fps. Physically rotate the unit and the display rolls to follow gravity.

Firmware flashing and updates happen from the app's right-click menu — no esptool, no Python, no buttons on the device. The zip bundles the firmware (atom-fw\): flash a brand-new unit as-is, and the "update" item only lights up when the connected device is older than the bundled build (it never rewrites anything on its own).

DEMO 05 — ALWAYS-ON

Stop "preparing to measure". It's already measured.

The resident recorder ctm record archives every session into ~/.ctm/, append-only. However many Claude Code windows you open, whenever you start a new session — it's recorded, no configuration.

Measuring becomes slicing a time range after the fact:

●●● ctm query copy

$ ctm query -from "13:00" -session 1a2b3c4d

Survives reboots by resuming from byte offsets (no gaps, no double counting). The UI's history window drills down to per-prompt breakdowns.

DEMO 06 — PLAN LIMITS

Official usage % and measured burn, on the same line.

ctm fetches the official usage percentages Claude Code shows for your 5-hour and weekly limits, and records them next to what ctm measured in the same window. Knowing "at X% we had consumed Y" lets you reverse-engineer the window capacity.

$ ctm limits

plan usage limits  max / default_claude_max_20x

  5-hour limit
   usage     0.0% ............................
   resets    in 4h55m (08-22 20:09)
   measured  7 messages / 3.28M tokens / $2.074

* weekly - all models
   usage     8.0% ##..........................
   resets    in 106h45m (08-27 01:59)
   measured  1,036 messages / 275.44M tokens / $231.58
   capacity  3.44G tokens / ≈ $2895 (implied from this reading)
   left      ≈ $2663

Sampled every 5 minutes by the resident recorder. With multiple machines, the asymmetry — % is account-wide, measurements are per-machine — even lets you estimate what your other machines are burning.

FEATURES

Feature checklist

• Dedup — message.id + requestId (without it you overcount ~2×)
• Incremental reads — byte offsets; partial lines carried to the next tick
• Cache-aware pricing — 5m/1h writes and reads at their real rates
• 5-hour block detection — the actual rate-limit window, with history
• Burn rate & projection — linear extrapolation from the last 5 minutes
• -session new — meter only a session you're about to start
• -since-now — meter only from this moment on
• ctm query — slice the archive by time range; detects active work clusters
• Official usage recording — 5h / weekly % next to measured burn
• JSON output — pure ASCII, script-friendly (PowerShell / jq)
• Crash auto-recovery — the UI supervises the recorder and restarts it with evidence
• Double-start protection — heartbeat lock prevents duplicate recording
• ATOMS3R sub-monitor — a desk-top USB display (shipped since v0.2.0, flashed from the menu)

VS

Compared with the usual ways

Costs are estimates at Anthropic's public list prices. On flat-rate plans (Pro / Max) no actual billing occurs.

INSTALL

Install (just unzip)

Two prerequisites: the PC uses Claude Code (ctm reads its logs), and — only if you want plan-usage percentages — you are logged in to claude. No Go, no .NET, no Python to install.

1. Download ctm-*-windows-amd64.zip from Releases
2. "Extract All" into any folder (e.g. C:\tools\ctm) — keep the folder layout
3. Double-click CtmMonitor.exe at the top level → the recorder (bin\ctm.exe) starts automatically
4. For daily use: right-click → "Start with Windows"

ctm-0.1.1-windows-amd64.zip
├── CtmMonitor.exe   ← the one you double-click
├── bin\ctm.exe      CLI / recorder (started automatically)
├── README.md / INSTALL.txt / LICENSE

$ .\bin\ctm.exe status
recorder: running
  archive      C:\Users\you\.ctm
  today        588 messages / 100.77M tokens / $242.97

Building from source

$ winget install Git.Git GoLang.Go
$ git clone https://github.com/GridJapan/gClaudeTokenMonitor.git
$ cd gClaudeTokenMonitor
$ .\build.ps1
$ .\bin\CtmMonitor.exe

All it takes is Go 1.22+ and Git. CtmMonitor builds with the csc.exe that ships with Windows.