Decisions
User Tasks
FR-053: Cost & Token Tracking
Summary
Track token usage and API costs per session, skill, and agent to understand spending patterns and optimize expensive operations.
Problem / Motivation
Opus will increasingly use agents, scheduled tasks, and automated workflows — all consuming tokens. Without visibility into costs:
- No way to know which skills/agents are expensive
- Can’t detect cost spikes from loops or inefficient prompts
- Can’t budget or forecast monthly spend
- No data to justify optimization efforts (FR-009 Token Efficiency)
As autonomous features come online (briefings, monitoring, self-review), costs could grow unnoticed.
Proposed Solution
Lightweight tracking system that logs token usage per session and rolls it up into a dashboard.
Data Model
| Field | Description |
|---|
timestamp | When the session/action occurred |
session_id | Unique session identifier |
action_type | skill / agent / manual / scheduled |
action_name | e.g., /briefing, researcher-agent |
input_tokens | Tokens sent |
output_tokens | Tokens received |
model | Model used (opus, sonnet, haiku) |
estimated_cost | Calculated from token counts + pricing |
Open Questions
1. Data Source
Question: How to capture token usage data?
| Option | Description |
|---|
| A) Parse Claude Code session logs | Post-session extraction from ~/.claude/ logs |
| B) PostToolUse hook with estimation | Estimate tokens per tool call (imprecise) |
| C) API-level tracking | Only works for programmatic API calls, not Claude Code CLI |
Recommendation: Option A — Claude Code already logs usage. Parse after session ends.
Phase Overview
| Phase | Description | Status |
|---|
| Phase 1 | Manual tracking script + cost table | — |
| Phase 2 | Automated post-session logging | — |
| Phase 3 | Dashboard + alerting | — |
Phase 1: Manual Tracking —
Goal: Script to extract token usage from recent sessions.
| File / Feature | Details | Owner | Status |
|---|
src/tracking/cost_tracker.py | Parse Claude Code logs for token counts | opus | — |
| Pricing table | Model → cost-per-token mapping | opus | — |
vault/00_system/dashboards/cost-dashboard.md | Markdown dashboard with weekly/monthly totals | opus | — |
Phase 2: Automated Logging —
Goal: Auto-log after every session.
| File / Feature | Details | Owner | Status |
|---|
| Post-session hook or cron | Trigger cost extraction after session | opus | — |
| SQLite storage | Persistent cost data in data/opus.db | opus | — |
| Per-skill breakdown | Attribute costs to specific skills/agents | opus | — |
Test
Manual tests
| Test | Expected | Actual | Last |
|---|
| Verify per-model pricing is correct | Matches current Anthropic pricing | pending | - |
AI-verified tests
| Scenario | Expected behavior | Verification method |
|---|
| … | … | … |
E2E tests
Integration tests
Unit tests
| Component | Tests | Coverage |
|---|
| … | … | … |
History
| Date | Event | Details |
|---|
| 2026-03-12 | Created | Identified as gap — no visibility into token costs |
References
- FR-009 (Token Efficiency Guidelines) — tracking validates whether efficiency measures work
- FR-014 (MCP Server Configuration) — sqlite MCP would store cost data
- FR-025 (Daily Briefing System) — could include daily cost summary