Flesh out PLAN.md with two-architecture implementation detail

Expand the planning document to implementation-ready detail. Both
viable data paths are specified independently so either can ship:

- Architecture A (OTEL-native): full docker-compose stack mirroring
  Anthropic's claude-code-monitoring-guide (otel-collector on 4317
  / 4318 / 8889, Prometheus on 9090, Grafana on 3000), Claude Code
  env vars, PromQL queries for each gauge, Python daemon sketch
  that queries Prometheus and serves /usage.

- Architecture B (ccusage-sourced): subprocess invocation of
  ccusage CLI for 5h blocks and 7d daily aggregates, watchdog
  JSONL tail for sub-second tach responsiveness, Python daemon
  sketch with a 60s RateBus ring buffer.

Hardware specified: X27.168 stepper motors driven by the Arduino
SwitecX25 library on ESP32 (Arduino C++ since no MicroPython port
exists), concrete GPIO pin assignments, ULN2003A driver notes,
annunciator LED wiring, enclosure notes.

Also captured: metric schema from Claude Code's OTEL docs,
prior-art review (ccusage / Claude-Code-Usage-Monitor / Grafana
Labs dashboards 25052 and 24993 / Anthropic's monitoring guide),
six-phase delivery plan, comparison table of A vs B, recommendation
(A for homelab-as-enterprise framing), and a metrics brainstorm
for later phases.

README updated to summarise both architectures and point at the
expanded plan.

Refs #1

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jeff Smith 2026-04-17 19:18:59 -06:00
parent a683828e6b
commit 08eaa63300
2 changed files with 721 additions and 293 deletions

978
PLAN.md

File diff suppressed because it is too large Load diff

View file

@ -1,19 +1,31 @@
# claude-gauge
Hardware instrument cluster plus companion web dashboard for Claude
Code session telemetry.
Hardware instrument cluster displaying Claude Code session telemetry.
A local Python daemon tails `~/.claude/projects/**/*.jsonl`, parses
structured events into rolling windows and aggregate stats, and
exposes them over HTTP. An ESP32 or Pi Pico drives a three-gauge
analog cluster on the desk (tokens/min tach, 5h fuel, 7d fuel) with
an annunciator row of model and warning lamps. A browser dashboard
on the same port surfaces the deep stats.
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.
See [PLAN.md](PLAN.md) for architecture, the instrument cluster
layout, the dashboard sections, the full metrics brainstorm, and
the phasing plan.
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 (daemon MVP) is the first issue.
Scaffolded. Phase A pending architecture decision and first issue.