tokenomics

Tokenomics — durable team usage telemetry

The efficiency-audit skill answers "what did this cost" by reading live transcripts — precise, but transcripts expire (~30 days) and live on each engineer's machine, so the answer is only available to whoever runs it, soon enough, where the work happened.

This skill closes that gap with a capture layer: an optionally-enabled hook that writes one JSON line per finished session into a git-committed ledger (.agents/telemetry/automation/usage-<user>.jsonl). Ledger lines are grounded in the same sources efficiency-audit trusts (transcript token records, ccusage dollars, Copilot's billed credits) but are captured at the moment they exist — so the team's usage history survives transcript cleanup and accumulates through ordinary git push/pull. A report script then answers: how much time, tokens and money did the team spend, and how many cases did it automate.

Installing this skill does NOT start capturing. Telemetry activates only when someone runs the install script below — that's the opt-in.

Updating an old install: re-run the same script. It is idempotent and also migrates the flat-era layout — usage-*.jsonl, scopes/, live/, config.json sitting at the telemetry ROOT move into automation/ automatically (readers look only there; un-migrated history would silently drop out of every report). Same-named newer data in automation/ wins — nothing is ever clobbered.

Quick start

# 1. Enable capture in this repo (all three hosts; idempotent; --remove undoes it)
node .claude/skills/tokenomics/scripts/install-hooks.mjs            # Claude-installed copy
node .github/skills/tokenomics/scripts/install-hooks.mjs            # Copilot-installed copy
#    --host claude|copilot|vscode   default wires Claude hooks + the Copilot hooks
#                                   file. `vscode` is OPT-IN (a folderOpen task in
#                                   shared .vscode/tasks.json; VS Code asks each
#                                   teammate once to allow auto-tasks) — every sweep
#                                   already walks the sidebar store, so it is only
#                                   needed in a SIDEBAR-ONLY repo. --remove strips
#                                   it either way.
#    --local       Claude only: settings.local.json (just you, not the team)
#    --git-hook    optional belt-and-braces: a background post-commit sweep
#    --doctor      health-check wiring, stores, ccusage, OTel flow (--fix starts the sink)
#    --otel [--endpoint URL]   opt into OpenTelemetry (see below); --otel-remove undoes

# 2. Backfill what's still on this machine (optional, one-time)
node .claude/skills/tokenomics/hooks/telemetry-capture.mjs --sweep --all

# 3. One commit to main (the installer prints it): registers the telemetry
#    submodule. From then on hooks commit+push the records to the `telemetry`
#    branch automatically — nobody hand-commits telemetry again.
#    Teammates: git clone --recurse-submodules

# 4. The report — one repo or several, a window, markdown / JSON / HTML
node .claude/skills/tokenomics/scripts/install-hooks.mjs --pull  # merge the team's pushes first
node .claude/skills/tokenomics/scripts/team-report.mjs
node .claude/skills/tokenomics/scripts/team-report.mjs ~/work/repoA ~/work/repoB --since 2026-08-01 --json
node .claude/skills/tokenomics/scripts/team-report.mjs --html --out team.html # shareable self-contained page
node .claude/skills/tokenomics/scripts/team-report.mjs --role test-automation-engineer   # sessions involving that agent

# 5. Per-batch cost — what a batch delivered and what it cost, per case
node .claude/skills/tokenomics/scripts/team-report.mjs --batch <slug>            # markdown
node .claude/skills/tokenomics/scripts/team-report.mjs --batch <slug> --html --out batch.html
node .claude/skills/tokenomics/scripts/team-report.mjs --batches                 # every batch with a receipt

# 6. Hyperfactory dataset export — one submission row per batch
#    identity comes from .agents/telemetry/automation/factory-profile.json (copy
#    templates/factory-profile.template.json there and fill it in once);
#    every `work-scope.mjs close` ALSO auto-appends the batch's row to
#    .agents/telemetry/automation/export/runs.json and prints the §7 checks
node .claude/skills/tokenomics/scripts/build-tokenomics-export.mjs --batch <slug>        # build/refresh one row + print its checks
node .claude/skills/tokenomics/scripts/build-tokenomics-export.mjs --submission          # datasets/<factory-id>/{runs.json,submission.md} + § 7 checklist status
node .claude/skills/tokenomics/scripts/build-tokenomics-export.mjs --submission --anon   # same, identifiers anonymized (T-WI-###) for the public PR
node .claude/skills/tokenomics/scripts/build-tokenomics-export.mjs --compare a/cost.json b/cost.json