archeious/claude-gauge
1
0
Fork 0
Code Issues 1 Pull requests 1 Projects Releases Packages Wiki Activity Actions

Flesh out PLAN.md with two-architecture implementation detail

Browse source 
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
Show stats Download patch file Download diff file Expand all files Collapse all files

978
PLAN.md
View file

File diff suppressed because it is too large Load diff

36
README.md
View file

@ -1,19 +1,31 @@
# claude-gauge # claude-gauge
Hardware instrument cluster plus companion web dashboard for Claude Hardware instrument cluster displaying Claude Code session telemetry.
Code session telemetry.
A local Python daemon tails `~/.claude/projects/**/*.jsonl`, parses Three analog needle gauges (5h fuel, tokens/min tach, 7d fuel) plus
structured events into rolling windows and aggregate stats, and an annunciator row of model-indicator and warning lamps, driven by
exposes them over HTTP. An ESP32 or Pi Pico drives a three-gauge an ESP32 polling a local Python daemon. The daemon reads either
analog cluster on the desk (tokens/min tach, 5h fuel, 7d fuel) with Claude Code's native OpenTelemetry feed through a Prometheus stack
an annunciator row of model and warning lamps. A browser dashboard (architecture A) or `ccusage` CLI aggregates with a direct JSONL
on the same port surfaces the deep stats. tail for the tach (architecture B). Firmware and cluster are
identical across both.
See [PLAN.md](PLAN.md) for architecture, the instrument cluster Fighter-jet / race-car aesthetic. Physical-first: all the deep
layout, the dashboard sections, the full metrics brainstorm, and stats live in Grafana (A) or ccusage's own surfaces (B). The dial
the phasing plan. 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 ## Status
Scaffolded. Phase A (daemon MVP) is the first issue. Scaffolded. Phase A pending architecture decision and first issue.