cost-metering

Original source / Raw SKILL.md

---
name: "cost-metering"
description: "Track and manage API costs across sessions. Budget alerts, model routing for cost optimization, spend reports. Use when: cost check, budget status, how much spent, optimize costs, cost tracking."
---

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


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### reference/cost-tracking-guide.md

```markdown
# Cost Tracking Guide

## Data Format

### daily-cost.json (Current Day)
```json
{
  "date": "2026-02-07",
  "spent": 2.40,
  "budget_monthly": 100,
  "budget_daily": 5,
  "alerts": {
    "info": 0.5,
    "warn": 0.8,
    "block": 0.95
  }
}
```

### cost-log.jsonl (Append-Only Log)
```json
{"phase":"research","model":"haiku","est_tokens":10000,"est_cost":0.003,"ts":"2026-02-07T10:30:00-05:00"}
{"phase":"feature-build","model":"sonnet","est_tokens":50000,"est_cost":0.15,"ts":"2026-02-07T11:00:00-05:00"}
{"phase":"review","model":"haiku","est_tokens":8000,"est_cost":0.002,"ts":"2026-02-07T11:30:00-05:00"}
```

## Tracking Methods

### Automatic (Recommended)
The workflow-orchestrator cost gate tracks spend automatically when you use the standard workflows (Start Day, Feature Build, End Day).

### Manual Logging
After expensive operations:
```bash
echo '{"phase":"[PHASE]","model":"[MODEL]","est_tokens":[N],"est_cost":[COST],"ts":"'$(date -Iseconds)'"}' >> ~/.claude/cost-log.jsonl
```

### Token Estimation
Most Claude Code sessions use roughly:
- Simple query: 5K-10K tokens
- Code generation: 20K-50K tokens
- Large refactor: 50K-100K tokens
- Full feature build: 100K-300K tokens

## Reporting Queries

### Today's spend
```bash
jq '.spent' ~/.claude/daily-cost.json
```

### This week by model
```bash
cat ~/.claude/cost-log.jsonl | jq -s '
  map(select(.ts >= "'$(date -v-7d +%Y-%m-%d)'"))
  | group_by(.model)
  | map({model: .[0].model, total: (map(.est_cost) | add), ops: length})
'
```

### Cost per phase
```bash
cat ~/.claude/cost-log.jsonl | jq -s '
  group_by(.phase)
  | map({phase: .[0].phase, total: (map(.est_cost) | add), avg: (map(.est_cost) | add / length)})
  | sort_by(-.total)
'
```

```

### reference/budget-templates.md

```markdown
# Budget Templates

## Hobby/Personal ($50/month)
```json
{
  "budget_monthly": 50,
  "budget_daily": 2,
  "alerts": {"info": 0.5, "warn": 0.7, "block": 0.9},
  "strategy": "Haiku-first. Sonnet only for code generation. No Opus."
}
```

## Professional ($100/month)
```json
{
  "budget_monthly": 100,
  "budget_daily": 5,
  "alerts": {"info": 0.5, "warn": 0.8, "block": 0.95},
  "strategy": "Sonnet default. Haiku for search/review. Opus for architecture."
}
```

## Team/Enterprise ($500/month)
```json
{
  "budget_monthly": 500,
  "budget_daily": 25,
  "alerts": {"info": 0.5, "warn": 0.8, "block": 0.95},
  "strategy": "Sonnet default. Opus when needed. Parallel agents OK."
}
```

## Monthly Budget Calculator

| Activity | Frequency | Model | Est. Cost |
|----------|-----------|-------|-----------|
| Start Day scan | 20/mo | haiku | $0.40 |
| Feature builds | 10/mo | sonnet | $20.00 |
| Code reviews | 15/mo | haiku | $0.30 |
| Research sprints | 5/mo | sonnet | $5.00 |
| Debug sessions | 8/mo | sonnet | $8.00 |
| End Day sweep | 20/mo | haiku | $0.40 |
| **Total** | | | **~$34/mo** |

Most developers spend $30-60/month with Sonnet-default routing.

```