agent-cost

claude-agent-cost

Cost analytics, budget alerts, and tier-rollup reporting on top of Claude Code's official OpenTelemetry.

What this plugin is

A query-time consumer of telemetry the substrate already produces:

• Authoritative cost source: Claude Code's claude_code.cost.usage metric — USD-attributed per API request by Claude Code itself, with query_source ∈ main|subagent|auxiliary. We do not duplicate this.
• Workflow correlation: agent.session_context events from claude-agent-telemetry — link claude.session.id → workflow.branch / workflow.issue_number.
• Tier rollup: tiers.yml (shared with agent-telemetry) maps subagent_type → haiku|sonnet|opus for cross-model bucketing.

What it ships

Path	Purpose
bin/cost-report.sh	Joins cost metric + session_context + tier mapping; prints markdown table by branch / issue / tier / agent / model / day / session
bin/cost-budget-check.sh	Alert-ladder check against config/budgets.yml; exits 1 on hard_stop
bin/cost-export.sh	Periodic Prometheus textfile export of cost rollups
config/pricing.yml	Fallback / override pricing — only used when CC's cost.usage is unavailable or for what-if analysis
config/budgets.yml	Budget definitions (empty by default — opt-in)
skills/cost-report	/cost-report --by <dim> [--since <duration>]
skills/cost-budget-check	/cost-budget-check [--budget <name>]
agents/cost-analyst	Haiku-tier read-only analyst — surfaces tier mismatches, cache outliers, fan-out outliers, budget pacing
docs/SETUP.md	End-to-end setup, including PreToolUse hook integration for budget gating
docs/QUERIES.md	PromQL / LogQL / TraceQL reference for cost analysis

Install

/plugin marketplace add laran/claude-methodology
/plugin install agent-telemetry@claude-methodology   # required substrate
/plugin install agent-cost@claude-methodology

Then docs/SETUP.md.

Quick start

# Cost split by query_source over the last day
bin/cost-report.sh --by tier --since 24h --filter query_source=subagent

# Cost per branch over the last week
bin/cost-report.sh --by branch --since 7d

# Budget check (after editing config/budgets.yml)
bin/cost-budget-check.sh --format json

Architecture

                ┌──────────────────────────────────────────┐
                │  Claude Code's official OTel              │
                │   claude_code.cost.usage  (USD)           │
                │   claude_code.token.usage{type, model,    │
                │                            query_source}  │
                └─────────────────┬────────────────────────┘
                                  │
                ┌─────────────────┴──────────────────────┐
                │                                        │
                ▼                                        ▼
          Prometheus                         Loki (agent.session_context
          (cost / token metrics)              events from agent-telemetry)
                │                                        │
                └────────────────┬───────────────────────┘
                                 ▼
                       bin/cost-report.sh
                       bin/cost-budget-check.sh
                                 │
                                 ▼
                    /cost-report, /cost-budget-check,
                    cost-analyst agent

What this plugin is NOT

• Not a cost emitter. Claude Code's metric is authoritative.
• Not a tier-mapping owner. tiers.yml is shared with agent-telemetry.
• Not a router or dispatch policy. That's agent-orchestration.
• Not a destructive controller. cost-budget-check.sh exits non-zero; it doesn't kill dispatches itself. The CALLER (a hook, cron, CI) is responsible for halting work.

v1.0 limitations

• --by agent falls back to --by model granularity; precise per-subagent_type rollup needs to join cost with the trace-level subagent_type attribute. Tracked for v1.1.
• --by day does not bucket per-day; use Grafana time-series panels for daily breakdowns. Tracked for v1.1.
• Budget filters in v1.0 only support query_source. tier, branch_pattern, model planned for v1.1.

License

MIT.