cost-metering

What this skill does

<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:**
```bash
cat ~/.claude/daily-cost.json 2>/dev/null || echo "No tracking yet"
```

**Initialize tracking:**
```bash
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
```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
```bash
cat ~/.claude/daily-cost.json | jq '{date, spent, remaining: (.budget_daily - .spent), pct: ((.spent / .budget_monthly) * 100 | floor)}'
```

### Weekly Report
```bash
# 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
```bash
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`:
```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.