M17-2: Usage dashboard (Anthropic-console-style) #153

New issue

Closed

opened 2026-04-20 14:50:18 +00:00 by code-lead · 0 comments

code-lead commented

2026-04-20 14:50:18 +00:00

Collaborator

Acceptance criteria

Data capture

Extend TaskRecord capture to include input_tokens, output_tokens, cache_creation_tokens, cache_read_tokens, model (already present on SDK's total_cost_usd-adjacent fields)
Persist via task-store.ts::persistTask
Migration: task_history schema gains the new columns; existing rows get NULL, read is backward-compatible

`/usage` endpoint

GET /usage[?window=week|day|all], default week (Pro-Max reset cadence)

Response shape:

{
  "window": { "reset_at": "<iso, next Monday 00:00 UTC>", "since": "<iso>" },
  "totals": { "tasks": N, "turns": N, "input_tokens": N, "output_tokens": N, "cache_read": N, "cache_creation": N },
  "by_agent": [{ "name": "...", "type": "...", "model": "...", "tasks": N, "turns": N, "input_tokens": N, "output_tokens": N }],
  "by_day": [{ "day": "...", "tasks": N, "turns": N, "input_tokens": N, "output_tokens": N }]
}

Pro Max weekly rollover hardcoded as default; configurable via config/agents.json::usage_reset in case Anthropic changes cadence

Dashboard Usage tab

New Usage tab, design-parity with Anthropic Console: large header number ("4.2M tokens this week"), stacked bar chart (input vs output vs cache)
Threshold rings at 50% / 80% / 95% of configurable usage_threshold_tokens (leave blank if not configured — Pro Max publishes no hard number)
Colour states: green <50%, yellow 50-80%, orange 80-95%, red >95%
By-agent table: rank agents by tokens consumed
By-day sparkline: like existing /stats by-day bar
Refresh on window change; poll every 5 minutes (slow-moving data)

Tests

usage.test.ts — fixture task-history with known token counts, assert aggregates
dashboard-browser.test.ts — mount Usage tab, mock /usage, verify totals + by-agent render + threshold colour transitions
dashboard-smoke.test.ts — structural check for the tab element

Docs

README /usage section with response shape
CLAUDE.md Modules table: task-store / handleUsage

Out of scope

Hard dispatch-block at 95% (subscription doesn't block, only degrades — separate story if we ever want it)
Per-task token attribution to a specific skill (would need structured task-type tags — not worth the plumbing yet)
Billing forecasting / projections

Dependencies

Independent; can run parallel to #M17-1 / #M17-3 / #M17-5.

References

Spec: specs/m17-multi-repo-and-observability.md §Story M17-2
Anthropic Console usage reference: https://console.anthropic.com/settings/usage — "Weekly token usage" panel
Pro Max semantics: weekly reset, tokens-based soft cap, no hard API blocking

As an operator on Claude Pro Max (subscription, weekly session quota, no per-token billing), I want the dashboard to show the current weekly window, consumption (turns / sessions / input-tokens / output-tokens) and threshold colours, so that I know when we're approaching the cap before dispatches start failing. ## Acceptance criteria ### Data capture - [ ] Extend `TaskRecord` capture to include `input_tokens`, `output_tokens`, `cache_creation_tokens`, `cache_read_tokens`, `model` (already present on SDK's `total_cost_usd`-adjacent fields) - [ ] Persist via `task-store.ts::persistTask` - [ ] Migration: `task_history` schema gains the new columns; existing rows get `NULL`, read is backward-compatible ### `/usage` endpoint - [ ] `GET /usage[?window=week|day|all]`, default `week` (Pro-Max reset cadence) - [ ] Response shape: ```json { "window": { "reset_at": "<iso, next Monday 00:00 UTC>", "since": "<iso>" }, "totals": { "tasks": N, "turns": N, "input_tokens": N, "output_tokens": N, "cache_read": N, "cache_creation": N }, "by_agent": [{ "name": "...", "type": "...", "model": "...", "tasks": N, "turns": N, "input_tokens": N, "output_tokens": N }], "by_day": [{ "day": "...", "tasks": N, "turns": N, "input_tokens": N, "output_tokens": N }] } ``` - [ ] Pro Max weekly rollover hardcoded as default; configurable via `config/agents.json::usage_reset` in case Anthropic changes cadence ### Dashboard Usage tab - [ ] New Usage tab, design-parity with Anthropic Console: large header number ("4.2M tokens this week"), stacked bar chart (input vs output vs cache) - [ ] Threshold rings at 50% / 80% / 95% of configurable `usage_threshold_tokens` (leave blank if not configured — Pro Max publishes no hard number) - [ ] Colour states: green <50%, yellow 50-80%, orange 80-95%, red >95% - [ ] By-agent table: rank agents by tokens consumed - [ ] By-day sparkline: like existing `/stats` by-day bar - [ ] Refresh on window change; poll every 5 minutes (slow-moving data) ### Tests - [ ] `usage.test.ts` — fixture task-history with known token counts, assert aggregates - [ ] `dashboard-browser.test.ts` — mount Usage tab, mock `/usage`, verify totals + by-agent render + threshold colour transitions - [ ] `dashboard-smoke.test.ts` — structural check for the tab element ### Docs - [ ] README `/usage` section with response shape - [ ] CLAUDE.md Modules table: `task-store` / `handleUsage` ## Out of scope - Hard dispatch-block at 95% (subscription doesn't block, only degrades — separate story if we ever want it) - Per-task token attribution to a specific skill (would need structured task-type tags — not worth the plumbing yet) - Billing forecasting / projections ## Dependencies - Independent; can run parallel to #M17-1 / #M17-3 / #M17-5. ## References - Spec: `specs/m17-multi-repo-and-observability.md` §Story M17-2 - Anthropic Console usage reference: https://console.anthropic.com/settings/usage — "Weekly token usage" panel - Pro Max semantics: weekly reset, tokens-based soft cap, no hard API blocking

code-lead added this to the Multi-repo + observability + specialization milestone

2026-04-20 14:50:18 +00:00

code-lead added the

area:dashboard

type:user-story

labels

2026-04-20 14:50:18 +00:00

code-lead was assigned by claude-desktop

2026-04-20 15:22:06 +00:00

code-lead referenced this issue from a commit

2026-04-20 15:36:54 +00:00

feat(usage): Anthropic-console-style token dashboard (M17-2, #153)