cost-report

cost-report

Surfaces cost rollups using Claude Code's authoritative claude_code.cost.usage metric (USD-attributed by Claude Code itself, per https://code.claude.com/docs/en/monitoring-usage).

Usage

/cost-report --by branch    [--since 7d]
/cost-report --by issue     [--since 24h]
/cost-report --by tier      [--since 1h]
/cost-report --by agent     [--since 24h]
/cost-report --by model     [--since 24h]
/cost-report --by day       [--since 30d]
/cost-report --by session   [--since 24h]
/cost-report --by tier --filter query_source=subagent

The skill shells out to bin/cost-report.sh, which:

1. Queries Prometheus for claude_code_cost_usage_total, summed by session_id (or model for --by tier|model|agent), over the requested window.
2. For dimensions that need workflow context (branch, issue, day, session), queries Loki for agent.session_context events to resolve session_id → workflow.branch / workflow.issue_number.
3. For --by tier, rolls up models via the active tiers.yml (resolution order: $AGENT_TIERS_FILE env var, project's .claude/agent-tiers.yml, agent-telemetry's bundled config/tiers.yml).
4. Renders a markdown table sorted by cost descending.

v1.0 limitations

• --by agent currently falls back to --by model granularity. True per-subagent_type rollup needs to join the cost metric with the trace-level subagent_type attribute (Claude Code's claude_code.tool spans). Tracked for v1.1.
• --by day rolls up over the entire window without per-day buckets; use Grafana time-series panels for daily breakdowns. Tracked for v1.1.

Backend dependencies

• Claude Code emitting OTel — CLAUDE_CODE_ENABLE_TELEMETRY=1.
• Prometheus scraping the collector — for the cost metric.
• Loki receiving from the collector — for agent.session_context events from the agent-telemetry plugin.
• jq, curl, and (for cost-budget-check) yq on PATH.

See docs/SETUP.md.