CLAUDE.md

@@ -0,0 +1,100 @@
+# 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](https://forgejo.labbity.unbiasedgeek.com/archeious/claude-gauge/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](https://forgejo.labbity.unbiasedgeek.com/archeious/claude-gauge/wiki/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](https://forgejo.labbity.unbiasedgeek.com/archeious/claude-gauge/wiki/SessionRetrospectives)).
+
+### 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](https://forgejo.labbity.unbiasedgeek.com/archeious/claude-gauge/wiki/Session1).