# claude-gauge

Hardware instrument cluster displaying Claude Code session telemetry.

Three analog needle gauges (5h fuel, tokens/min tach, 7d fuel) plus
an annunciator row of model-indicator and warning lamps, driven by
an ESP32 polling a local Python daemon. The daemon reads either
Claude Code's native OpenTelemetry feed through a Prometheus stack
(architecture A) or `ccusage` CLI aggregates with a direct JSONL
tail for the tach (architecture B). Firmware and cluster are
identical across both.

Fighter-jet / race-car aesthetic. Physical-first: all the deep
stats live in Grafana (A) or ccusage's own surfaces (B). The dial
on the desk is the ambient summary.

See [PLAN.md](PLAN.md) for:

* Instrument cluster layout and annunciator semantics
* Architecture A: Docker Compose stack, Claude Code env config,
  PromQL queries, daemon sketch
* Architecture B: ccusage subprocess integration, watchdog tail,
  daemon sketch
* Hardware: X27.168 steppers, SwitecX25 library, ESP32 wiring,
  enclosure notes
* Six-phase plan from daemon MVP through enclosure V1
* Full metrics brainstorm for later phases

## Status

Scaffolded. Phase A pending architecture decision and first issue.