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