101 lines
4.1 KiB
Markdown
101 lines
4.1 KiB
Markdown
|
# 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).
|