diff --git a/Session1.md b/Session1.md new file mode 100644 index 0000000..2c1013b --- /dev/null +++ b/Session1.md @@ -0,0 +1,289 @@ +# Session 1 Notes — 2026-04-17 + +## What We Set Out to Do + +Start new. No pre-existing goal entering the session; the project +was conceived mid-conversation. The arc: + +1. Design an MCP framework between AI agents and budget / finance + software (quartermaster context; produced a proposal document). +2. Side-track on whether Claude Max plan usage is available + programmatically. +3. From that, conceive claude-gauge: a physical analog instrument + cluster displaying Claude Code session telemetry. +4. Scaffold the project, do prior-art research, plan architecture + options, synthesize a multi-page wiki. + +## What Actually Happened + +### Part 1: quartermaster MCP proposal + +Jeff asked for an AI-agent framework over budgeting software. Initial +design was enterprise-sized (read/propose/commit layers, auth scope +models). He pushed back: "I think you are thinking too large in +scope. This is a simple personal budget." Correct call. I retrenched +twice and then read the quartermaster wiki to align against the +actual shipped model. Produced `docs/MCPProposal.md` in quartermaster +(now PR #24). Never committed in-session; cleaned up in the wrap-up. + +### Part 2: Discord plugin side-track + +"What is the Discord Claude plugin?" led to the claude-code-guide +agent confirming the official plugin + bot-in-server pattern. Jeff +followed up with "can Claude Code act as me on Discord?" Answer: +technically yes, but Discord ToS prohibits selfbots. Jeff killed +the idea cleanly: "I was looking for the unsanctioned path ... I +don't want to risk my account." No argument, moved on. + +### Part 3: claude-gauge conception + +"Is the Max plan usage available programmatically? I want to build +a hardware representation of it (an analog needle gauge)." Research +showed no official API; JSONL tailing is the workaround. Designed a +file-watcher daemon plus short rolling windows ("not just 5-hour, +also 1-minute for real-time cooking signal"), then Jeff expanded to +"like an instrument cluster in a fighter jet or race car." That +reframed everything. Created the project folder, PLAN.md with the +design, README.md. + +### Part 4: Prior-art check + +Jeff: "search the web to see if other projects of this nature exist." +Found that the **software side is crowded** (ccusage, Claude-Code +-Usage-Monitor, multiple Grafana dashboards, Anthropic's own +`claude-code-monitoring-guide`), and that Claude Code has native +OpenTelemetry support. Reshaped the plan: don't rebuild the +telemetry layer, consume it. Physical cluster remains the unique +contribution. Two viable data-path architectures (A: OTEL + Prom, +B: ccusage) feeding the same firmware. + +### Part 5: Plan expansion (Jeff away) + +Jeff left for dinner with explicit authorization: "Do not ask for +my input. Fully plan out A and B independently. ... make me proud." +Did three rounds of targeted web searches to fill in OTEL metric +schema, Docker Compose specifics, ccusage MCP tool schema, +SwitecX25 driver library status. Wrote PLAN.md to ~670 lines with +architecture A (full docker-compose, otel-collector-config, prom +config, Claude Code env, PromQL, daemon sketch) and architecture B +(ccusage CLI + watchdog tail + daemon sketch). Hardware specified +down to GPIO pin map. Filed issue #1, opened PR #2. + +### Part 6: Images + wiki + +Jeff dropped two renders: "Monitor Dash.png" (a refined four-gauge +cluster) and "exotic dashes.png" (four stylistic variants: +steampunk chronometer, retro VFD array, minimalist birch e-ink, +bio-digital cybernetic). Synthesized all content into a six-page +wiki (Home, Architecture, DataSources, Hardware, Roadmap, Ideas). +Inserted the Monitor Dash render in README.md and Home.md; exotics +on Ideas.md. Moved images to `docs/images/` in main repo, +gitignored `docs/wiki/`. + +Adopted the render's **four-gauge layout** as canonical (5h fuel, +tach, thinking ratio, cache hit) over the original three-gauge +plan. The render dropped the 7d fuel in favor of the previously +optional thinking-ratio and cache-hit gauges. Cleaner signal. + +### Part 7: Deep ecosystem survey + +Jeff: "What other physical gauge projects of this nature did you +find? ... keep searching and digging deep. We want this project to +be really really cool." Ran additional rounds covering Hackaday +tags, home automation communities, Tindie/Etsy, ambient displays, +retro-future aesthetics. Found: + +- Liam Jackson's **CI tachometer dashboard** (closest cousin). +- McLear's **AstraDash** (car cluster -> Home Assistant via ESP32). +- Evan's **kegerator cluster** (Chevy gauges -> beer metrics). +- Ecasti's **PrometheusClient** (digital cousin pulling from Prom). +- Widespread steampunk-voltmeter + ESPHome pattern. + +Synthesized into a new `Ecosystem.md` wiki page with a "what to +borrow / where we uniquely contribute" matrix. Expanded `Ideas.md` +with nine unique-angle directions (physical model knob, swappable +faces, daily reset chime, tactile feedback, per-project LED strip, +cluster-to-cluster sync, physical commit button, audio toggle, +historical companion cluster). + +## Key Decisions & Reasoning + +### Adopt the four-gauge render as canonical + +The original PLAN.md had three primary gauges (5h, tach, 7d) with +two optional. The render painted four (5h, tach, thinking ratio, +cache hit) and dropped 7d. Why the render is right: + +- 7d moves on a timescale that doesn't need a needle. Grafana or + ccusage TUI is sufficient for it. +- Thinking ratio is a genuinely novel cognitive-state signal. + Nobody else has visualised this metric. Putting it on the + primary cluster makes the project more distinctive. +- Cache hit rate is bragging-rights AND responsive. Fits the + "cool needle motion" brief. +- Four needles balance visually better than three for a monitor + mount. + +### Architecture A (OTEL-native) over B (ccusage) as the recommendation + +Jeff's "homelab operates like an enterprise" framing is the +decider. OTEL is the platform feature Claude Code ships; Prometheus +integrates with the rest of the stack he already runs; Grafana +dashboard 25052 is a free deep-stats surface. B stays documented as +the faster-start path if Prometheus isn't available, but A is the +preference. + +### Motorcycle tachometers as a V1 path + +Liam Jackson's prior art showed you can drive cheap ($5-10) motor- +cycle tachs with frequency-based PWM from an Arduino. Stepping into +X27.168 + SwitecX25 is the "right" path but takes more build time. +For Phase C (single-needle proof-of-life), the motorcycle-tach +shortcut is documented as an option to ship-this-weekend first, +then upgrade later. + +### In-process Python MCP module for quartermaster (side-task) + +For the quartermaster MCP proposal, chose in-process Python (sibling +of the FastAPI app, `quartermaster-mcp` script entry point) rather +than a sidecar. Shares the service layer, same `QUARTERMASTER_DB_URL`, +no HTTP hop. Read/write mode gated by env var. Simple because +quartermaster is a single-user local app. + +## Surprises & Discoveries + +- **Claude Code has native OpenTelemetry.** I did not know this + entering the session. Knowing it reshaped the whole claude-gauge + architecture. Without it, we'd have ended up reinventing ccusage. + +- **Grafana dashboard 25052 already exists** for Claude Code. + Killing the "build our own web dashboard" phase of the plan was + immediate. + +- **ccusage has an HTTP MCP server.** The `blocks` tool gives + 5-hour summaries directly. Architecture B is much smaller than + I had initially sketched. + +- **Hardware space is genuinely empty** for LLM/AI-usage physical + displays. I was braced to find someone had already built this; + nobody has. + +- **Jeff renamed the tach "Night fuel" in the render** (an AI art + artifact rather than intent). Kept the "TOKENS/MIN" framing in + the wiki but noted the render label matter-of-factly. Zero + friction from Jeff. + +- **"Make me proud. You can do this."** Explicit autonomy grant + with emotional framing. Profile notes trust ceiling has been + rising; this is the highest explicit authorization I've been + given. Delivered a full research pass + implementation-ready + plan + PR while he was at dinner. + +## Concerns & Open Threads + +### Architecture decision still open + +Jeff has not committed to A or B. PR #2 recommends A but does not +force the choice. Before Phase A ships, this has to be decided, +because the Phase A daemon implementation differs. + +### MicroPython path dead + +SwitecX25 has no MicroPython port. Firmware will be Arduino C++, +not MicroPython. Jeff originally wanted MicroPython for ESP32; the +prior-art research surfaced the dead-end. Documented but worth +flagging again before Phase C. + +### No real measurements yet + +All ceilings in the plan (`CLAUDE_GAUGE_5H_CEILING`, redline) are +placeholders. Calibration is Phase E. Nothing blocks earlier +phases but worth tracking. + +### OTEL scrape interval vs tach responsiveness + +Architecture A's Prometheus scrape at 15s caps the tach's ability +to show real-time bursts. Planned mitigation: hybrid JSONL tail +for the tach only, if Phase E shows it's sluggish. Parked as a +known consideration. + +### Thinking tokens not in OTEL as a dedicated metric + +OTEL's `claude_code.token.usage` has `type` label with values +`input`/`output`/`cacheRead`/`cacheCreation`. Thinking tokens are +NOT a separate value. To drive the temp gauge under architecture A, +either derive from event stream (api_request with content type) +or fall back to tailing JSONL directly for that one gauge. +Documented as an open question in DataSources.md. + +### Quartermaster MCP proposal sitting in PR #24 + +Side-deliverable from Part 1. Doc only. Wrap-up cleanup filed it +properly. Will block on Jeff reviewing / merging when he's next +in quartermaster. + +## Raw Thinking + +- The session had a natural ADHD arc: one genuine problem + (quartermaster MCP) -> side-track (Discord) -> new project born + (claude-gauge) -> deep dive -> ecosystem research -> a working + skeleton. Jeff's protocols worked: nothing fell through, both the + quartermaster doc and the claude-gauge skeleton have PRs waiting. + +- Architecture A is the recommendation but architecture B is what I + would ship first if this were my project. Day 1 to ship on B is + half of A. Worth re-checking with Jeff: is he okay with the + Prometheus prerequisite, or does he want to be hands-on with + tokens sooner? + +- The "physical model-selector knob" idea in Ideas.md is the one I + keep coming back to. Turning the cluster into a tactile input + device materially distinguishes claude-gauge from every other + ambient display. Worth prototyping in Phase F alongside the + enclosure. + +- Motorcycle tachs vs X27.168 is a real fork. V1 motorcycle tachs + are fast and cheap but lose the "car cluster cohesion" aesthetic + the render sells. X27.168 with automotive-derived faces matches + the render but is harder to prototype. Worth Jeff's call before + Phase C. + +- The em-dash counter in Ideas.md is half-joke, half-serious. It + would be funny to have a needle that literally counts Claude's + own rule violations against the CLAUDE.md global instruction. + Useful as a self-policing visible metric. + +- This is the first time I've architected a project end-to-end in + a single session (previous projects had multiple sessions + accumulating). Pleased with the shape, worried about the usual + first-session overconfidence. Calibrate against Jeff's Phase A + feedback. + +## What's Next + +Priority order for the next session: + +1. **Decide architecture A vs B.** Blocks Phase A. Ask Jeff + directly; present the day-1-to-needle tradeoff. + +2. **Merge PR #2 (claude-gauge plan expansion)** after Jeff's + review. Once merged, delete the branch and close issue #1. + +3. **Merge PR #24 (quartermaster MCP proposal)** if Jeff reviews + and approves. Close issue #23. + +4. **File Phase A issue** on claude-gauge once architecture is + chosen: "daemon prints five window values to stdout." + +5. **Stand up architecture A stack** (if A chosen): Docker + Compose with the reference config, point Claude Code env at + the collector, verify metrics appear in Prometheus via the + `/api/v1/query` interface. Validates the plan before any + daemon code is written. + +6. **Alternative first move if B chosen**: install ccusage, run + `blocks --json` and `daily --json` once by hand, paste output + into a reference file. Then start daemon skeleton. + +7. **Phase C hardware decision**: confirm X27.168 + SwitecX25 vs + motorcycle tachometer V1 prototype. diff --git a/SessionRetrospectives.md b/SessionRetrospectives.md new file mode 100644 index 0000000..cd10499 --- /dev/null +++ b/SessionRetrospectives.md @@ -0,0 +1,7 @@ +# Session Retrospectives + +Index of per-session notes. Most recent first. + +| # | Date | Title | Link | +|---|---|---|---| +| 1 | 2026-04-17 | Conception, architecture design, wiki synthesis | [Session1](Session1) |