Usage System — The Brain

Overview

Every delegate.py call is recorded in two places: stats/usage.json (aggregate totals) and stats/call_log.jsonl (permanent per-call history). All counters are additive — they accumulate across the lifetime of the project and are never reset or averaged.

stats/usage.json — Aggregate Totals

A single structured JSON object updated after every call. Tracks lifetime totals per provider plus a rolling window of the last 100 calls for display:

{
  "providers": {
    "mistral": {
      "provider":      "mistral",
      "calls":         26,
      "tokens":        27038,
      "cost_usd":      0.0,
      "total_latency": 253840,
      "errors":        0
    }
  },
  "total_calls":    57,
  "total_tokens":   36143,
  "total_cost_usd": 0.0,
  "claude_calls":   0,
  "claude_tokens":  0,
  "worker_tokens":  36143,
  "first_call_ts":  1746100000.0,
  "last_call_ts":   1746200000.0,
  "call_log":       [ ... ]
}

stats/call_log.jsonl — Permanent Per-Call Log

Append-only JSONL file — one JSON object per line, never truncated. The complete history of every delegate call ever made:

{"ts": 1746200000.0, "provider": "mistral", "type": "creative", "tokens": 1167, "ms": 4004}
{"ts": 1746200060.0, "provider": "cerebras", "type": "factual_qa", "tokens": 51, "ms": 478}

Key Metrics

Metric	Where	Description
`calls` / `tokens` / `cost_usd`	usage.json per-provider	Lifetime totals — additive, never reset
`total_latency`	usage.json per-provider	Sum of all latencies; divide by calls for average
`worker_tokens`	usage.json top-level	Tokens handled by non-Claude providers — the primary savings metric
`claude_tokens_saved`	Computed property	Alias for `worker_tokens`
`estimated_savings_usd`	Computed property	`worker_tokens / 1000 × Claude Sonnet rate`
`call_log`	usage.json	Last 100 calls for display only — not the source of truth

report.py

Run python report.py for a terminal usage summary. Tier labels (FREE / PAID) are read live from the adapter REGISTRY — no hardcoded list. Flags: --json for machine-readable output, --reset to wipe all stats.

push_stats.py

Run python push_stats.py at the end of each session to inject live stats into the GitHub README and push. Health block failures are non-fatal — stats always publish even if the health block cannot be built.

update_readme_stats.py

Lower-level script called by push_stats.py. Injects two auto-managed blocks into README.md:  and . Flags: --stats-only, --dry-run, --push.