feat(telemetry): deterministic claude code token measurement, release 1

[blafourcade]

🎯 What & why

Replaces the previous telemetry with a deterministic token count for Claude Code. Every billed call is counted exactly once and stored locally. The report breaks the calls down by person, session, model, day, repository, task and ticket, and every axis sums to the same total. The task comes only from an explicit declaration, and nothing is sent anywhere.

Contract: spec.md. Plan: plan.md. Product contract: usage-contract.md.

🛠️ How it works

• Count. Ingest reads Claude transcripts incrementally, by byte offset. The key is message.id:requestId and duplicates are folded globally: the largest total wins, then the earliest time, then the lowest session id. Synthetic messages are dropped. Each advisor iteration becomes its own record. Cache writes are summed over the message iterations, and an unknown counter stays null, never 0. (contexts/telemetry/domain)
• Store. The ledger is local and split by month. Each partition is rewritten only when its content changes, under a lock. Branch bindings are kept as snapshots, so a deleted or reused branch name keeps its past.
• Declare. aidd telemetry task <name> [--ticket <ref>] | --none binds the session and the working branch; branch bindings live in local git config. The plugin hooks ask once per unbound working branch, only for Claude, only when a person is present, and only where consent is open. A declaration typed as a prompt is parsed by a strict tokenizer and run without a shell, so it never reaches the model. A /clear or /branch keeps the task. (hooks)
• Attribute. Precedence is the session declaration in force, then the carry, then the branch declaration in force, else unattributed with a reason. The first declaration in a carried session covers that whole session.
• Consent, per clone. aidd telemetry on writes aidd.telemetry=2:<token> to local git config and opens an interval. A call is stored only if its clone had an open interval at the call's time. A clone is identified by its common dir's dev, ino, birth time and realpath. There is no backfill before on; that is a user decision, because backfill was the source of every consent hole the reviews found. Nothing is committed, so a teammate is never measured without running on.
• Status. aidd telemetry status shows whether this clone is measured, since when, and its task.
• First ingest. A transcript last written more than a day before the first on is not read: on a real 6.2 GB history the first ingest goes from over 22 minutes (never finished) to 246 s, the next takes 1.1 s, and the stored calls match an independent count (5 calls, 217,337 tokens).
• Asking. One line to ask, one line to confirm a declaration, tried in a real session.
• Tools. Ingest reads one reader per tool (its format and its transcripts). A second tool is its format, its source, one wiring line and its name; storage, attribution and the report stay as they are.
• Opt out and forget. off closes the interval. forget previews first; with --yes it erases both versions' data and the git keys. The previous version's leftovers are cleaned on on.

🧪 How to verify

• cd cli && pnpm test (6,448 tests), pnpm test:mutation:telemetry (96.2, floor 96), bash scripts/smoke-tools.sh; node --test 'scripts/__tests__/**/*.test.js' (434).
• Whole journey on the built binary with the real hooks: telemetry-journey.e2e.test.ts. Consent scenario table: consent-scenarios.integration.test.ts.
• Every rule has a scripted mutation that turns its test red: mutation-proofs.md.
• Counting checked against an independent reader on a real history projected into a sandbox: 262,328 calls over 68 days, no day differing (real-history-oracle.md).

⚠️ Heads-up

• Draft. CI is green on Linux and Windows, every tier including the end-to-end journey (run 38291026139, every mutation scope above its floor). macOS has no CI job: the full suite passes there locally. Windows is tested by CI only: a real session started from an 8.3 short path (RUNNER~1) was not tried, and neither was the cmd /s launch of an npm shim on a real install.
• Presence. Asked in the terminal and the desktop app. Not in IDE extensions: VS Code shows no hook message. Declare there from a terminal; it binds the branch.
• Residual limits are listed in the contract:
  • a manual git config off is not seen if no hook or ingest runs before the clone is deleted;
  • inode reuse where the file system keeps no birth time;
  • pid reuse;
  • clock skew;
  • on a file system with no birth time, a clone made again at a deleted one's path is told apart only once ingest has seen it;
  • where Linux refuses statx (seccomp, kernel before 4.11), the birth time Node reports is the change time, so the identity moves at each entry added to the git dir. The clone stops being measured; off also closes the interval its key names at its path, so it fails closed. Simulated (statx made to fail under strace): 0 of 36 rows stored more, 3 runs; before that change one row stored a call made after off.
• Birth time on Linux. A birth time equal to the change time is kept as a birth. Treating it as no birth made the row "copy at the path" store one call too many on Linux, because the file clock is coarse. Measured in Docker, on btrfs: 3 failures in 150 runs at millisecond resolution, 5 and 8 in 300 at nanosecond resolution, 0 in 400 with the new rule. On ext4, as an unprivileged user: 81 in 200 with the old rule, 0 in 400 with the new (mutation-proofs.md).
• Performance. At 265k records, ingesting one call takes about 3 s, because the whole month is rewritten. A declaration takes under 1 s, even while an ingest holds the lock.
• Session id join, probed. The CI job identifier-join runs the installed claude -p against a dead API and checks, through the shipped hook predicates, that the hook's payload, its environment and every transcript line name one session, that CLAUDE_PID is set, and that a headless run never reads as a person present (probe-identifier-join.cjs). It holds on 2.1.295.
• Bundle budget. Lowered from 734 KB to 667 KB, which is the measured 656 KB plus about 2 % (removing V1 freed the room).
• Overlap. fix(aidd-telemetry): keep a worktree's sessions in every report, even after the worktree is removed #988 changes V1 telemetry code that this branch removes. A maintainer should decide the merge order.

✅ I certify

• I DO CERTIFY I READ EACH LINE OF THE PULL REQUEST BECAUSE I AM A SOFTWARE ENGINEER, NOT A AI PUPPY.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VWNxk63AGKkqE8HRqHLjGp