From 5665a8f953b6ca114aed54f70591047ab15a86e4 Mon Sep 17 00:00:00 2001 From: Lovebug MCP Date: Thu, 9 Jul 2026 23:09:30 +0000 Subject: [PATCH] =?UTF-8?q?mcp:=20project-plan=20=E2=80=94=20tokened=20?= =?UTF-8?q?=E2=80=94=20Claude=20Code=20session=20token=20dashboard?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Sources/Homelab/tokened.md | 48 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 Sources/Homelab/tokened.md diff --git a/Sources/Homelab/tokened.md b/Sources/Homelab/tokened.md new file mode 100644 index 0000000..da13644 --- /dev/null +++ b/Sources/Homelab/tokened.md @@ -0,0 +1,48 @@ +--- +created: '2026-07-09' +path: Sources/Homelab +project: tokened +tags: +- homelab +- podman +- traefik +- observability +- claude-code +- tokens +type: project-plan +--- + +## Goal +Visualize where the context window goes across Lovebug (herbyadmin) Claude Code sessions — turn the raw JSONL we've been hand-grepping into a standing, glanceable dashboard. Born from a session that hit 708k/1M and the question "where did it all go?" + +## Success criteria +1. **Up and reachable** — `tokened.herbylab.dev` resolves through Traefik, loads, no auth wall; container runs rootless as herbyadmin reading `~/.claude/projects` read-only. +2. **Sees the real data** — herbyadmin's sessions appear across all project folders (not just lovebug-instructions), including the 3-day marathons; session list populated and browsable. +3. **Numbers are trustworthy** — dashboard's total for at least one known session roughly matches that session's `/context` reading, validating the message.id dedup. Separates "pretty" from "true." +4. **Answers the founding question** — for any session, see token breakdown by category and spot heavy hitters (e.g. read_worker_transcript-heavy, Bash-heavy patterns) without touching a terminal. +5. **Cool graphs.** Non-negotiable. Heatmaps and per-prompt cost charts render and are nice to look at. An unopened dashboard is a failed dashboard. + +## Build shape +- **Source:** fork upstream `nateherkai/token-dashboard` into Gitea petal-power org; build from the fork, pinned commit. Fork is load-bearing (expect local patches), not cosmetic. +- **Runtime:** rootless Podman, run as herbyadmin on herbys-dev. `--userns=keep-id` → container is herbyadmin, reads own files natively. +- **Mounts:** `~/.claude/projects` → `:ro`. SQLite cache → named volume, writable, herbyadmin-owned. +- **Lifecycle:** manual `podman start` (fish abbr for convenience). No systemd. Dies on reboot until poked — accepted for v1. +- **Ingress:** Traefik file-provider route → `tokened.herbylab.dev`. Wildcard cert. No auth (private VLAN, behind server). +- **Container build:** Lovebug writes the Containerfile — `python:3.12-slim`, stdlib-only app, no build step. +- **Deploy tree:** `/opt/projects/homelab/tokened/`. +- **Stack fit:** first Podman tool on herbys-dev (rest is Docker) — deliberate low-stakes sandbox for the rootless model. + +## Open questions — Lovebug resolves via survey before building +1. **Config surface** — does the app take `CLAUDE_PROJECTS_DIR` / a cache-path / `PORT` / `HOST` via env, or are paths hardcoded to `~/.claude/projects/`? Read the scanner source. Determines whether the mount path must match the app's expectation or can be redirected. Biggest "won't-just-work" risk. +2. **Bind address** — app defaults to `127.0.0.1`; inside the container it must bind `0.0.0.0` (container netns is the boundary) so Traefik can reach it. Confirm PORT/HOST are settable. +3. **Source-tagging** — deferred to build time by design. Goal is to tag each session by source-agent (orchestrator / worker / interactive) using JSONL fields (agentType, parentToolUseId) — richer than folder-tagging. Survey whether upstream exposes this as a dimension or flattens it; if flattened, this is fork-patch #1. Work out during build. + +## Design principle +Static, on-demand tool — read when opened, no live streaming. Upstream's 30-second re-scan is unwanted; disable or ignore. Keep as many axes in the data as possible (source-agent, project-folder, tool-type, per-prompt cost, cache-hit, time) — slicing them is the point. + +## Validation checkpoint +Once up, sanity-check dashboard total vs `/context` for a known session (criterion 3). Rough agreement = dedup works, numbers trustworthy. Divergence = don't trust it, investigate. This is the fun part. + +## Out of scope / v2 negative-space +- Reboot persistence (Quadlet / systemd-user lingering) — accepted manual for now, explore later. +- Deep axis-slicing / custom graphs beyond upstream defaults — the fork roadmap, not v1. \ No newline at end of file