claude-gauge/CLAUDE.md

claude-gauge (repo instructions)

What this is

Hardware instrument cluster displaying Claude Code session telemetry in real time. Four analog needles (5h fuel, tokens/min tach, thinking ratio, cache hit) plus annunciator row, driven by an ESP32 polling a local Python daemon. Full documentation lives in the wiki.

Current Project State

• Phase: pre-Phase-A. Scaffolded, planned, not yet implementing.
• Last worked on: 2026-04-17
• Last commit on main: a683828 — Initial scaffold
• Open PRs: #2 (flesh out PLAN.md, add wiki + README image)
• Open issues: #1 (flesh out PLAN.md; tracked by PR #2)
• Architecture decision: open. PR #2 recommends A (OTEL + Prometheus) over B (ccusage + JSONL tail). Must be chosen before Phase A ships because the daemon implementation differs.
• Migrations: n/a (no DB yet)
• Blocking issues: architecture choice

Project conventions

• Issue-driven work: every change ties to a Forgejo issue. Branch as feat/<issue>-<slug>.
• Atomic commits. One logical change each.
• Merge via Forgejo API / UI, not git merge locally. Delete remote branch, git pull --ff-only, delete local branch, close the tracking issue manually.
• Wiki checkout lives at docs/wiki/ (gitignored in the main repo; it is its own git repo against archeious/claude-gauge.wiki.git).

Where things live

• PLAN.md — working notes and full two-architecture plan.
• README.md — short overview, render image, wiki pointer.
• docs/images/ — tracked images (monitor-dash, exotic-dashes).
• docs/wiki/ — local wiki checkout; commit and push separately to the wiki remote.
• src/claude_gauge/ — Python package skeleton (no runtime code yet).
• tests/ — test skeleton.
• pyproject.toml — uv-managed Python 3.12+, no dependencies declared yet (picked per architecture).

Architecture choice (open)

See DataSources for specifics. Short form:

	A. OTEL-native	B. ccusage-sourced
Data source	Claude Code OTLP -> Prom	ccusage CLI + JSONL tail
Day 1 to ship	Two (stand up stack first)	One
Deep-stats dashboard	Grafana 25052 free	None / ccusage TUI
Homelab-enterprise fit	Strong	Weak

Default recommendation: A.

Session Log

Most recent 3 sessions (full history in the wiki).

Session 1 — 2026-04-17

Greenfield conception through a full two-architecture plan and seven-page wiki. Notable milestones:

• Project conceived mid-session from "can we read Claude Max usage programmatically" -> "I want an analog needle gauge for it" -> "like an instrument cluster in a fighter jet."
• Prior-art research: software side of LLM-usage tracking is crowded (ccusage, Claude-Code-Usage-Monitor, multiple Grafana dashboards, Anthropic's own monitoring guide). Physical-gauge variant for LLM usage has zero prior art.
• Claude Code ships with native OpenTelemetry support; architecture A piggybacks on it. Grafana dashboard 25052 is a free deep-stats surface.
• Architecture B (ccusage CLI + watchdog tail) is documented as the faster-start alternative.
• Adopted the image-rendered four-gauge layout (5h fuel, tach, thinking ratio, cache hit) over the original three-gauge plan. The 7d window moves too slowly to warrant a needle.
• Hardware path: X27.168 steppers + Arduino SwitecX25 library on ESP32 Arduino C++ (no MicroPython port exists). Motorcycle tachometers documented as a V1 shortcut (Liam Jackson's prior art).
• Seven wiki pages: Home, Architecture, DataSources, Hardware, Ecosystem, Roadmap, Ideas. Monitor Dash render on Home and README; exotic variants on Ideas.
• PR #2 open against main with the full plan; issue #1 tracks it.

One side-deliverable: a quartermaster MCP proposal document drafted earlier in the session (now PR #24 on that repo).

Full retro: Session1.