chore: add CLAUDE.md for session 1
Repo-level CLAUDE.md captures current project state (pre-Phase-A, architecture decision open, PR #2 in flight), project conventions, where things live, and the session 1 log pointing at the wiki retrospective.
This commit is contained in:
Jeff Smith
parent
fdab957b55
commit
1bfe151baf
1 changed files with 100 additions and 0 deletions
100
CLAUDE.md
Normal file
100
CLAUDE.md
Normal file
|
|
@ -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).
|
||||
Loading…
Reference in a new issue