Owner directive 2026-05-27 15:29: track Claude usage workspace-wide with the lightest-touch mechanism that still gives a useful per-day / per-week view, and expose enough signal that the manager can proactively drain backlog when the weekly window is near reset (use the budget, don't waste it).
| Option | Mechanism | Cost | Verdict |
|---|---|---|---|
| (a) Anthropic Admin API usage_report | Requires an admin API key (org-scoped). | Auth setup; needs admin key in 1P. | Not chosen for now — no admin API key found in Employee vault under a quick scan. Flagged below as a follow-up. |
| (b) Claude Code Stop / SessionEnd hook | Hook reads stdin JSON containing per-session token counts, appends to a log. | Tiny shell hook. Only fires on session end — partial coverage if sessions are killed. | Possible but redundant given (c). |
| (c) Parse local transcript JSONL under ~/.claude/projects/**/*.jsonl | Each assistant message stores message.usage.{input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens} with an ISO timestamp. | Zero infra; one Python script; covers everything Claude Code already records. | CHOSEN. Lightest-touch, no auth, no daemons, retroactive (works on historical data). |
| (d) Langfuse / Helicone | External proxy/SaaS. | Wiring + cost + privacy. | Overkill. |
scripts/claude-usage-summary.sh — Python-in-Bash, no deps beyond python3.
./scripts/claude-usage-summary.sh # last 7 days, prive workspace
./scripts/claude-usage-summary.sh --days 30 # last 30 days
./scripts/claude-usage-summary.sh --weekly # add current ISO-week window estimate
./scripts/claude-usage-summary.sh --all-projects # include every ~/.claude/projects/* dir
Sums per UTC day across all transcript JSONL files for the prive workspace.
Columns: msgs, input (true input + cache_creation), cache_cr,
cache_rd, output. Cache reads are ~10% of input cost — shown raw so the
ratio of fresh vs. cached input is visible.
The transcript files contain everything the hook would write, plus historical data going back across all past sessions. A hook would add a second log to keep in sync without giving any new signal. If we later want real-time nudges (e.g. "you crossed 80% of weekly budget mid-session"), revisit (b).
Anthropic enforces a rolling weekly token cap on Claude Code plans.
The exact reset moment is per-account and is not exposed by the transcript
files. We approximate with ISO week (Mon 00:00 UTC .. next Mon 00:00 UTC)
and surface it via --weekly.
Manager policy: in the last 6–12 hours before the weekly window resets, the manager should proactively drain the human-actions / IN-FLIGHT backlog rather than let budget expire. Concretely:
./scripts/claude-usage-summary.sh --weekly and read hours_left.hours_left <= 12 and weekly input + cache_create is well below the
plan's known cap → schedule additional worker bursts on queued backlog.What the tracking still needs to make this airtight (follow-ups):
Employee vault would let us replace the approximation. FLAG: no
admin key was located on a quick scan — owner action: create one in the
Anthropic console and stash as Anthropic Admin API Key in Employee.usage_report and render a bar..swarm/bus.log for the owner.--days 30 for trend.scripts/claude-usage-summary.sh — the script.docs/human-actions.md — IN-FLIGHT entry for the admin-key follow-up + this policy.
Reacties