agent-usage

Agent Usage

Token usage for all AI harnesses (agy, claude, codex, copilot, grok, opencode) is recorded to ~/.agents/usages/<harness>/<session_id>.json on session completion and turn boundaries.

Directory Layout & Schema

Every session record is stored atomically with permissions 0o600:

~/.agents/usages/
├── agy/
│   └── <session_id>.json
├── claude/
│   └── <session_id>.json
├── codex/
│   └── <session_id>.json
├── copilot/
│   └── <session_id>.json
├── grok/
│   └── <session_id>.json
└── opencode/
    └── <session_id>.json

Each record contains:

{
  "timestamp": "2026-09-03T18:00:00Z",
  "harness": "claude",
  "agent": "claude",
  "session_id": "abc-123",
  "model": "claude-opus-5",
  "input_tokens": 12500,
  "output_tokens": 3400,
  "cached_tokens": 82000,
  "cache_write_tokens": 1200,
  "reasoning_tokens": 0,
  "total_tokens": 99100,
  "cost_usd": 0.1425,
  "turn_count": 8,
  "cwd": "~/project"
}

Commands

dot agent usage stats                                              # summary table of token usage per harness
dot agent usage stats --by-model                                   # break down token usage by harness and model
dot agent usage stats --harness claude                             # filter stats to a specific harness
dot agent usage stats --since 24h --json                           # emit json array for scripting
dot agent usage list -n 20                                         # list recent session records
dot agent usage show claude <session_id>                           # inspect a specific session record
dot agent usage sync                                               # scan raw stores and backfill missing records
duckdb -c "SELECT harness, count(*), sum(total_tokens) FROM read_json_auto('~/.agents/usages/*/*.json', union_by_name=true) GROUP BY harness" # ad-hoc SQL

Workflow

1. Check aggregate usage: run dot agent usage stats to inspect overall token consumption and costs across harnesses.
2. Break down by model: run dot agent usage stats --by-model when comparing prompt efficiency or model tiers.
3. Filter by time window: pass --since 24h or --since 7d to isolate a recent sprint or experiment.
4. Deep dive with DuckDB: query ~/.agents/usages/*/*.json directly with read_json_auto in duckdb for custom aggregations, percentiles, or CSV exports.
5. Synchronize historical sessions: run dot agent usage sync after adding an integration to extract metrics from historical transcripts.