cost-metering

Track Claude API costs across sessions with budget alerts, model routing optimization, and spend reporting. Integrates with workflow-orchestrator's cost gate for automated budget enforcement.

<quick_start> Check current spend:

cat ~/.claude/daily-cost.json 2>/dev/null || echo "No tracking yet"

Initialize tracking:

mkdir -p ~/.claude
echo '{"date":"'$(date +%Y-%m-%d)'","spent":0,"budget_monthly":100,"budget_daily":5}' > ~/.claude/daily-cost.json

</quick_start>

<success_criteria>

• Daily cost tracking initialized at ~/.claude/daily-cost.json
• Budget alerts fire at 50% (info), 80% (warn), and 95% (block) thresholds
• Model routing applied: Haiku for search/classify, Sonnet for code, DeepSeek for bulk
• Cost-per-feature metric available via portfolio-artifact integration
• Monthly spend stays within configured budget ($100/mo default) </success_criteria>

- "cost check", "budget status", "how much spent" - "optimize costs", "cost tracking", "budget alert" - "model routing", "cheaper model", "cost report"

---

Model Rates (Current)

Model	Input/1M tokens	Output/1M tokens	Typical Use
Claude Opus 4.6	$5.00	$25.00	Architecture, complex reasoning
Claude Sonnet 4.6	$3.00	$15.00	Code generation, standard tasks
Claude Haiku 4.5	$1.00	$5.00	Search, classification, simple
DeepSeek V3	$0.27	$1.10	Bulk processing
GROQ Llama 3.3 70B	$0.59	$0.79	Fast inference
Voyage Embeddings	$0.10	—	Embeddings

v1.1.0 pricing changes: Opus $15/$75 → $5/$25 (70% cheaper with Opus 4.6). Haiku $0.25/$1.25 → $1/$5 (Haiku 3 → 4.5, 4x more expensive). Sonnet $3/$15 unchanged (model upgraded 4.5 → 4.6).

---

Budget Configuration

~/.claude/daily-cost.json

{
  "date": "2026-02-07",
  "spent": 2.40,
  "budget_monthly": 100,
  "budget_daily": 5,
  "alerts": {
    "info": 0.5,
    "warn": 0.8,
    "block": 0.95
  }
}

Alert Thresholds

Threshold	% Budget	Action
Info	50%	Display: "50% of monthly budget used"
Warn	80%	Yellow alert: "⚠️ 80% budget — consider model downgrade"
Block	95%	Red alert: "🛑 95% budget — require explicit override to continue"

---

Cost Optimization Strategies

1. Model Routing (biggest impact)

Task	Expensive	Optimized	Savings
File search	Sonnet ($3/1M)	Haiku ($1/1M)	67%
Code review	Sonnet ($3/1M)	Haiku ($1/1M)	67%
Classification	Sonnet ($3/1M)	Haiku ($1/1M)	67%
Bulk processing	Sonnet ($3/1M)	DeepSeek ($0.27/1M)	91%

Rule: If the task doesn't generate code, use Haiku. If it doesn't need Claude, use DeepSeek.

2. Context Management

• Keep SKILL.md files under 200 lines (progressive disclosure)
• Load reference files only when needed
• Use Explore agent with haiku model for codebase search
• Avoid reading entire files — use Grep to find specific lines

3. Task Batching

• Group related searches into one Explore agent call
• Use parallel subagents (haiku) instead of serial sonnet calls
• Combine file reads when possible

---

Tracking Commands

Daily Spend Check

cat ~/.claude/daily-cost.json | jq '{date, spent, remaining: (.budget_daily - .spent), pct: ((.spent / .budget_monthly) * 100 | floor)}'

Weekly Report

# Aggregate daily logs
cat ~/.claude/cost-log.jsonl | jq -s 'group_by(.phase) | map({phase: .[0].phase, total: (map(.est_cost) | add), count: length})'

Monthly Summary

cat ~/.claude/cost-log.jsonl | jq -s '{
  total: (map(.est_cost) | add),
  by_model: (group_by(.model) | map({model: .[0].model, cost: (map(.est_cost) | add)})),
  by_phase: (group_by(.phase) | map({phase: .[0].phase, cost: (map(.est_cost) | add)}))
}'

---

Integration Points

System	How
workflow-orchestrator	Cost gate checks budget before workflows
subagent-teams	Model selection uses cost tiers
agent-capability-matrix	Includes model recommendations
portfolio-artifact	Reports cost-per-feature metrics
End Day protocol	Logs daily costs, updates MTD
TaskCreate/TaskUpdate	Zero API cost — local UI tool for progress tracking
TeamCreate/SendMessage	Zero API cost — local coordination (but spawned agents incur model costs)

---

Storage

~/.claude/
├── daily-cost.json          # Current day's budget + spend
├── cost-log.jsonl           # Append-only operation log
└── portfolio/
    └── daily-metrics.jsonl  # Includes cost-per-feature

Deep dive: See reference/cost-tracking-guide.md, reference/budget-templates.md

Emit Outcome Sidecar

As the final step, write to ~/.claude/skill-analytics/last-outcome-cost-metering.json:

{"ts":"[UTC ISO8601]","skill":"cost-metering","version":"1.1.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"sessions_tracked":[n],"total_cost_usd":[n],"budget_alerts":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

Use status "partial" if some stages failed but results were produced. Use "error" only if no output was generated.