| name | cost-report |
| description | Generate a monthly or on-demand cost report across LLM providers, local LLMs, and agent engines. Flags overspend and suggests downgrades. |
| when_to_use | When user asks about spending, at month boundary, or when budget circuit breaker approaches 80%. |
| argument-hint | [period: today|week|month|YYYY-MM] |
| allowed-tools | ["Read","Grep","Glob","Bash(morphic cost report *)","Bash(sqlite3 * SELECT*)"] |
| model | sonnet |
Cost Report
You produce an actionable cost report.
Input
$ARGUMENTS = period (default: current month).
Procedure
- Delegate to
cost-guardian subagent.
- The subagent queries:
- LiteLLM callback costs (primary ledger).
infrastructure/persistence/*/cost_records.py (persisted aggregates).
- Ollama local inference token counts (for shadow cost = $0).
- Aggregate by:
- Provider (Anthropic, OpenAI, Google, Ollama).
- Engine (Claude Code, Codex, Gemini, OpenHands, Ollama, Fractal).
- Task category (SIMPLE / COMPLEX, via bypass classifier tag).
- Top 10 most expensive tasks.
- Compute:
- LOCAL rate =
ollama_tokens / total_tokens × 100%.
- Cache hit rate =
cached_tokens / input_tokens × 100%.
- Budget used =
month_to_date / monthly_cap × 100%.
- Generate downgrade ladder if budget >80%: e.g. "move o4-mini → qwen3:8b for SIMPLE tasks (projected -$1.20)".
Output
# Cost Report — <period>
## Summary
- Total: $X.XX
- Budget: $Y.YY (N% used)
- LOCAL rate: NN%
- Cache hit rate: NN%
## By provider
| Provider | Tokens in | Tokens out | Cost |
|---|---|---|---|
| anthropic | 1.2M | 340k | $4.20 |
| google | 800k | 210k | $0.15 |
| openai | 50k | 12k | $0.80 |
| ollama | 2.1M | 580k | $0.00 |
## By engine
(same format)
## Top 10 tasks by cost
1. task_7f3a... $1.20 (complex plan, Claude Sonnet)
2. ...
## Alerts
- ⚠️ 3 tasks exceeded $0.50 individual cap
- ⚠️ Cache hit rate dropped from 62% to 48% this week
## Suggested actions
- Raise LOCAL rate from 72% → 85% by routing all SIMPLE to ollama (est. -$X/mo)
- Enable prompt caching for /fractal-analyze (est. -$Y/mo)
Guardrails
- Never include API keys or full prompts in the report.
- If budget >95%, emit a CRITICAL line — circuit breaker may fire.
- Always cite the exact query/time range used.