# Budget Tracking

Post-hoc budget enforcement inspired by Paperclip's budget system.

## How it works

1. `budget-hook.sh` runs as a PostToolUse hook after every tool call
2. Each call is logged to `budget/cost-events.jsonl`
3. After logging, cumulative cost is compared against `BUDGET.md` policy
4. If soft threshold (default 80%) exceeded: warning to stderr
5. If hard threshold (100%) exceeded and hard_stop=true: creates `budget/PAUSED`
   flag file, subsequent tool calls are blocked (exit 2)

## Why post-hoc, not pre-run?

Paperclip uses the same approach. Pre-run budget reservation requires a
persistent service or lock file coordination. Post-hoc checking is simpler
and robust enough in practice — the worst case is one extra run before pause.

## Cost estimation

The current implementation counts events as a rough proxy for cost. For
accurate cost tracking, you have two options:

1. **Admin API** (org accounts only): Query `/v1/organizations/cost_report`
   with an Admin API key (`sk-ant-admin...`). This gives actual USD costs.
2. **Token estimation**: Parse token counts from Claude's responses and
   multiply by published per-token prices. More accurate than event counting
   but still an estimate.

For headless runs, `claude -p --max-budget-usd N` provides a per-run
budget cap directly in the CLI.

## Integration

Add to `.claude/settings.json`:
```json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "*",
      "hooks": [{"type": "command", "command": "bash budget/budget-hook.sh"}]
    }]
  }
}
```