Jeff Smith 08eaa63300 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>

2026-04-17 19:18:59 -06:00

1.2 KiB

Raw Blame History

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 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.

1.2 KiB Raw Blame History

claude-gauge

Status

1.2 KiB

Raw Blame History