Roadmap

One phase per issue. No scope bleed between phases.

Shipped

#	Title	Merged
-	Initial scaffold and PLAN.md	2026-04-17
1	Flesh out PLAN.md with two-architecture implementation detail	PR #2 open

Phases

Phase A — daemon prints to stdout

Tail the telemetry source (OTEL-Prom or ccusage), maintain the five primary values in memory, print them to stdout every second. No HTTP, no hardware, no dashboard. First proof the numbers land.

Architecture A or B must be chosen before starting; the daemon implementation differs.

Exit criteria: Claude Code activity makes the values tick in a terminal.

Phase B — HTTP endpoint

Stand up FastAPI, expose GET /usage returning the documented JSON shape. Verify with curl from another machine on the LAN.

Exit criteria: curl http://<host>:8080/usage returns valid JSON with all fields populated.

Phase C — single needle

Minimal ESP32 firmware. Polls /usage, drives one stepper (the tach) and one LED (MODEL). Proves the hardware path end to end.

Exit criteria: the tach needle moves in response to typing into Claude Code.

Phase D — full cluster

Four steppers, full annunciator row. Wiring on a breadboard or solder-perf. No enclosure yet.

Exit criteria: all four gauges and all five lamps behave according to their specifications in Hardware.

Phase E — calibration

Run the cluster for a week of real use. Tune the three environment variables against observed behaviour. Document chosen values in this wiki.

Exit criteria: the fuel gauge reads roughly what ccusage blocks reports; the tach redline fires when you expect it to.

Phase F — enclosure V1

3D-printed bezel, cream faces, annunciator smoked-acrylic cover, monitor-mount bracket. Permanent install under the monitor.

Exit criteria: the cluster is a desk object you would show someone, not a breadboard.

Phase G — dashboard

Architecture A: import Grafana Labs dashboard 25052 against the Prometheus data source. Link it from the wiki Home.

Architecture B: decide whether to build a custom deep-stats page or just live in the ccusage TUI.

Exit criteria: a "look at everything" surface exists somewhere.

Phase H — character and cross-system metrics

Em-dash counter, phrase extractor, git correlation, Quartermaster correlation. Lowest priority, highest amusement. Ships as Grafana panels (A) or as a small web page (B).

Deferred

True stream-time tach. Requires a Claude Code hook (SessionStart / Stop / PostToolUse) pushing heartbeats. Dramatic work for modest gain over the JSONL tail.
Thinking-token metric via OTEL. Currently derivable only from events + prompt.id correlation; simpler to extract from JSONL content blocks directly in the tail.
Hybrid (A + B) daemon where fuel gauges come from Prometheus and tach comes from JSONL tail. Worth it only if Phase E shows the 15 s scrape interval feels sluggish.
Multi-machine cluster. If other homelab hosts start running Claude Code, point them at the same OTEL collector (architecture A) and the gauges become per-host aggregates.

Out of scope

MicroPython firmware. No maintained SwitecX25 port exists. Not worth writing one.
Battery operation. Always desk-powered.
Alexa / voice interfaces. No.
Cloud sync of gauge state. No.