claude-gauge/PLAN.md

claude-gauge

Hardware instrument cluster plus companion web dashboard for Claude Code session telemetry. Primary surface is a physical cluster on the desk (fighter-jet / race-car aesthetic). Secondary surface is a local web dashboard for the deep stats.

Problem

There is no official programmatic API for Claude Max plan usage today. The /usage and /status slash commands in Claude Code are interactive-only. Open feature requests (claude-code issues #40395, #13585, #27217, #33978) track this but nothing has shipped as of 2026-04-17.

Rather than wait, drive everything from local Claude Code state by watching the session transcript JSONL files in ~/.claude/projects/. Swap the data source later when Anthropic ships a real endpoint; the hardware, firmware, daemon API, and dashboard all stay the same.

Instrument cluster (primary surface)

Physical cluster on the desk. Three analog gauges across the top, annunciator row below. Backlit. Brushed aluminium bezel, black face, cream needles, burgundy redline zone (optional: match the quartermaster palette for a house aesthetic).

    +------------+   +--------------+   +------------+
    |   5h FUEL  |   |   TOKENS/MIN |   |  7d FUEL   |
    |   0 - 100% |   |  0 - redline |   |  0 - 100%  |
    +------------+   +--------------+   +------------+
    [OPUS] [SONNET] [HAIKU]   [HOT] [WARN] [STALL] [IDLE]

Primary gauges

Gauge	Input	Feel
Center tach	tokens/min, short rolling window	Jumpy, fun, shows when Claude is cooking
Left fuel	% of 5h plan window used	Slow, steady, tells you when to worry
Right fuel	% of 7d plan window used	Slowest, long-arc view of the week

Annunciator row

Lamp	Condition
OPUS / SONNET / HAIKU	lights the model that wrote the most recent tokens
HOT	flashes when tach crosses redline
WARN	solid when either fuel gauge is above 80%
STALL	lights after N minutes of JSONL silence (no activity)
IDLE	green "power on, daemon reachable" indicator

Model lamps are colour-coded: Opus deep red, Sonnet amber, Haiku green. Visual cue for why the tach just spiked.

Optional fourth gauge

If physical real estate allows, a "temp" or "boost" sub-gauge:

• Cache hit rate as a boost gauge. High cache read = cheap inference. Bragging-rights needle.
• Thinking-to-output ratio as a temp gauge. High = Claude is grinding; low = cruising. Tells you when a task is hard.

Companion web dashboard (secondary surface)

Same daemon serves a browser dashboard at http://<host>:<port>/ with the deep stats. Claude Code is already a terminal tool, so the dashboard lives alongside as a geek-out surface when you want to drill in past the three-needle summary.

Dashboard sections

1. Overview: the three gauges rendered in the browser, plus the annunciator row. Same data as the cluster, so a quick sanity check from any device on the LAN.
2. Rates and windows: line charts for tokens/min over last 1h, 6h, 24h. 5h and 7d window sums over the past month.
3. Cost: dollar estimates derived from token counts and published per-model pricing. Today, week-to-date, month-to-date, projected month.
4. Models: stacked time series by model (Opus / Sonnet / Haiku). Token split pie for the current 7d window.
5. Projects: tokens per project, time per project, last-active timestamp. Sortable table.
6. Tools: top tools by call count, success rate per tool, Bash command distribution (top commands by root executable).
7. Files: hottest files by Read + Edit count, edit-to-read ratio per file.
8. Rhythm: time-of-day heatmap, day-of-week heatmap, session duration distribution.
9. Raw events: streaming tail of the latest parsed JSONL rows, for debugging and to watch the data land.

Dashboard is read-only. Nothing the user does here mutates state.

Architecture

~/.claude/projects/**/*.jsonl
          |
          v (watchdog / inotify, line-append events)
          |
  [ gauge daemon ]  <--- local, Python, long-running
          |
          +-- parse new line -> structured event
          |     { ts, session_id, project, model, role,
          |       input_tokens, output_tokens,
          |       cache_read, cache_creation,
          |       thinking_tokens, stop_reason,
          |       tool_use: [...], is_sidechain, request_id }
          |
          +-- in-memory ring buffer (last ~60 min of events)
          +-- periodic flush of events + rolling aggregates to SQLite
          |
          +-- computed windows (primary, cluster):
          |     rate_instant    last 30s, tokens/min
          |     rate_1m         rolling 60s, tokens/min
          |     rate_5m         rolling 5m, tokens/min
          |     window_5h       rolling 5h sum
          |     window_7d       rolling 7d sum
          |
          +-- computed aggregates (secondary, dashboard):
          |     cache hit rate, thinking ratio, cost estimate,
          |     per-model token split, per-project totals,
          |     tool call counts, file touch counts, rhythm grids
          |
          +-- derived flags:
          |     hot, warn, stall, idle, last_model, last_project
          |
          +-- HTTP endpoints:
          |     GET  /usage        primary cluster payload
          |     GET  /stats        deep aggregates for the dashboard
          |     GET  /stream       SSE of parsed events (raw tail)
          |     GET  /             dashboard UI
          |
          v (poll every ~1s)
     [ ESP32 / Pi Pico, on LAN ]
          |
          +-- drives three needles via PWM + low-pass filter
              (or servos if full-swing dials are easier)
          +-- drives annunciator LEDs over GPIO
          +-- optional small OLED behind the cluster for raw numbers

Real-time honesty

Claude Code writes a JSONL line after each assistant message completes, not during streaming. The cluster therefore updates per-message, not per-token:

• Rapid back-and-forth with small messages: tach ticks steadily, feels alive.
• Opus cranking a 40-second response: tach reads zero, zero, zero, then SPIKES at the end with the full message's token count.

Still useful. The spike itself is informative ("that burn just hit 8k tokens in 40 seconds"). STALL lamp covers the "is it still working or is the session idle" ambiguity.

If true stream-time is wanted later, a Claude Code hook (SessionStart / Stop / PostToolUse) can push heartbeats into the daemon. Dramatically more work for modest gain. Park as v2.

Calibration

The daemon does not know Anthropic's real per-plan caps. User configures a local ceiling:

CLAUDE_GAUGE_5H_CEILING=<tokens>
CLAUDE_GAUGE_7D_CEILING=<tokens>
CLAUDE_GAUGE_TACH_REDLINE=<tokens/min>

Gauges read against those ceilings. Estimate from experience: run for a week at normal usage, note where /usage says you are vs where the dials read, adjust the config. Ship sensible defaults tunable per user.

Data source migration path

When Anthropic ships an official usage endpoint, the daemon replaces its input with that endpoint and drops the JSONL tailing. The HTTP shape it serves to the cluster stays the same. The dashboard gains accuracy but does not change structure. Zero hardware change, zero firmware change.

Stack (proposed, not decided)

Daemon: Python 3.12+, uv, watchdog for file tail, FastAPI for HTTP, SQLite for durable state, Jinja2 for dashboard templates, Alpine.js or HTMX for dashboard interactivity. Matches the house style (see quartermaster).

Firmware: MicroPython on ESP32 or Pi Pico W for the wifi stack. C/Rust if MicroPython HTTP polling turns out wobbly at the required update rate.

Hardware: three analog voltmeter movements (0-5V or similar) for the gauges, driven from PWM pins through low-pass filters, or tiny servos with printed needles. Annunciator row is discrete LEDs behind a smoked acrylic face.

Metrics brainstorm (for later inspection)

Everything on this list is parseable from the JSONL today. The MVP daemon only needs the primary-window stats; everything else lands under later issues. Capturing them here so they don't get forgotten.

Cost and tokens

• Total tokens by window (already primary)
• Breakdown: input / output / cache_read / cache_creation
• Cache hit rate = cache_read / (cache_read + cache_creation + input)
• Cache savings in dollars (cache reads are 10% of normal input cost)
• Cost per session at published per-model pricing
• Cost per day / week / month; projected month
• Opus / Sonnet / Haiku token split
• Server tool use: web_search_requests, web_fetch_requests per day
• Service tier distribution (standard vs priority)
• Ephemeral-1h vs ephemeral-5m cache split

Time and rhythm

• Sessions per day / per week, rolling average
• Session duration distribution
• Time-of-day heatmap (circadian work pattern)
• Day-of-week heatmap
• Longest continuous session on record
• Your think-time: gap between assistant-end and next user message
• Claude's work-time: user message to assistant complete
• Active vs idle ratio within sessions
• Streak tracking (consecutive days used)
• All-nighter detector (session crossing 2am local)

Work shape

• Thinking tokens counted from content blocks of type thinking
• Thinking-to-output ratio ("cogitation index")
• Stop-reason distribution (end_turn / tool_use / max_tokens); watch for rising max_tokens (responses getting cut off)
• Messages per session
• Tool calls per assistant response (parallelism indicator)
• User interrupt rate (sessions ending on cancel)
• Iteration count per task (assistant messages between two consecutive user prompts as a proxy)

Tool usage

• Top tools by count (Bash, Edit, Read, Grep, ...)
• Tool success vs failure rate
• Bash command distribution, parsed by root executable (git, python, uv, ls, ...)
• File reads / edits / writes per session
• Hottest files by touch count across all sessions
• Agent / subagent counts (isSidechain=true), subagent depth
• Web search / web fetch counts

Project and context

• Tokens per project (JSONL path encodes the project)
• Time per project
• Project switching rate within a session
• Dormant project detector (no activity in N days)
• Languages touched, derived from file extensions
• Last file edited per project (resume-where-you-left-off)

Friction and quality signals

• User message length distribution (one-word directives vs prose)
• Rough correction reflex count: user messages starting with "no", "wrong", "stop", "actually"
• Permission denial frequency
• Retry / regenerate patterns
• File-history-snapshot count per session (checkpoint density)

Character and fun

• Em dash violation count in assistant text (per the CLAUDE.md rule, a needle that reads "rule-break events this week")
• Emoji leakage count
• Most-used phrase by Claude in your transcripts
• Most-used phrase by you (captures your actual directive vocabulary)
• "Dude, chill" detector: count of explicit pushback against Claude
• Thank-you rate per session
• Silent sessions (ended without /compact or /clear)

Cross-system correlations (bigger, later)

• Git: commits produced per session, lines changed per token spent
• PRs / issues closed per session
• Quartermaster: correlate long Claude sessions with budget-editing days (just for fun)

Phasing

Phase A — daemon MVP

One issue. Tail JSONL, parse into structured events, maintain the five primary windows, print them to stdout every second. No HTTP, no hardware, no dashboard. Prove the numbers land correctly against Claude Code's own /usage output.

Phase B — HTTP + dashboard overview

Stand up FastAPI, expose GET /usage for the cluster and GET / for a dashboard overview page (three gauges rendered in SVG, same data as the cluster). No deep stats yet. First thing you can load in a browser.

Phase C — firmware + single needle

Minimal ESP32 / Pico firmware that polls /usage and drives one needle (the tach). Prove the hardware path end to end.

Phase D — full cluster

Two more needles + annunciator row. Enclosure prototype.

Phase E — dashboard deep stats

Cost panel, model panel, project panel, rhythm heatmaps, tool panel, file panel, raw-event tail. Pulls from the aggregate store the daemon has been building since Phase A.

Phase F — character and cross-system

Em-dash detector, phrase extractor, git correlation, quartermaster correlation. Lowest priority, highest amusement.

Next steps

1. Forgejo repo at archeious/claude-gauge (created alongside this plan).
2. File Phase A as the first issue.
3. Ship Phase A. See the five numbers tick up in a terminal while typing into Claude Code. First dopamine hit.
4. File follow-up issues one phase at a time. No scope bleed between phases.