---
name: cost-tracker
description: >
  Track and estimate token usage, costs, and budgets. Use before starting work to
  estimate costs, during work to log usage, and after work to compare estimates
  to actuals. Automatically invoked when planning delegation or completing phases.
autoInvoke: true
---

# Cost Tracker Skill

Track token usage and costs at every level: per task, per agent, per phase, and per project.

## Before Starting Work: Estimate

Before any delegated task or phase, produce a cost estimate:

```markdown
### Cost Estimate: [Task/Phase Name]
| Item | Model | Est. Input Tokens | Est. Output Tokens | Est. Cost |
|------|-------|-------------------|--------------------|-----------| 
| ...  | ...   | ...               | ...                | ...       |
| **Total** | | | | **$X.XX** |
| **Budget (2x)** | | | | **$Y.YY** |
```

### Estimation Guidelines

- Always budget **2x** the AI's initial estimate — this is a hard rule
- Include overhead: context loading, CLAUDE.md reading, tool calls, retries
- Subagents: each subagent loads its own context — count that separately
- Agent teams: multiply by team size plus inter-agent communication overhead (~5x baseline)
- For multi-turn tasks, estimate turns × average tokens per turn
- If you have historical data from `docs/evals/`, use it to calibrate

## During Work: Log

After completing a task or receiving results from a delegated agent, log the actual usage:

```markdown
### Cost Log: [Task Name]
- **Agent:** [name]
- **Model:** [model used]
- **Input tokens:** [actual]
- **Output tokens:** [actual]
- **Total tokens:** [actual]
- **Estimated tokens:** [from the estimate]
- **Variance:** [+/- %]
- **Retries:** [count]
```

Append to `docs/evals/cost-log-<project-slug>.md` (create if it doesn't exist).

## After Work: Summarize

At phase completion, produce a cost summary:

```markdown
### Phase Cost Summary: [Phase Name]
| Agent | Tasks | Est. Tokens | Actual Tokens | Variance | Est. Cost | Actual Cost |
|-------|-------|-------------|---------------|----------|-----------|-------------|
| ...   | ...   | ...         | ...           | ...      | ...       | ...         |
| **Phase Total** | | | | | | |

### Budget Status
- **Project budget:** $X
- **Spent to date:** $Y
- **Remaining:** $Z
- **Projected total:** $W (based on current burn rate)
```

## Budget Checks

Before starting any task, check:

1. **Is there enough budget remaining?** If projected cost exceeds remaining budget, alert the user.
2. **Is the provider quota sufficient?** Check rate limits and remaining API credits if possible.
3. **Is the 2x buffer still intact?** If actual costs are consistently hitting the buffer, raise the multiplier.

## Rules

- Never start work without an estimate presented to the user
- Log actual usage after every delegated task — no exceptions
- If actual exceeds 2x estimate, pause and alert the user before continuing
- Cost data feeds into Phase 8 — maintain it rigorously
- Track per-provider if multiple models are in use (e.g., Opus for planning, Sonnet for execution)