agent-builder/scripts/templates/budget

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:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "*",
      "hooks": [{"type": "command", "command": "bash budget/budget-hook.sh"}]
    }]
  }
}