cost-metering by @scientiacapital

<objective> 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. </objective>

<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>

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

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.