Kjell Tore Guttormsen ec6f7c150e feat(templates): add budget tracking templates (Paperclip pattern)

Session 4 step 16 — post-hoc enforcement via PostToolUse hook with
PAUSED flag, budget-report.sh aggregates spend against window limit.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-04-12 06:55:33 +02:00

1.5 KiB

Raw Blame History

Budget Tracking

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

How it works

budget-hook.sh runs as a PostToolUse hook after every tool call
Each call is logged to budget/cost-events.jsonl
After logging, cumulative cost is compared against BUDGET.md policy
If soft threshold (default 80%) exceeded: warning to stderr
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:

Admin API (org accounts only): Query /v1/organizations/cost_report with an Admin API key (sk-ant-admin...). This gives actual USD costs.
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"}]
    }]
  }
}

1.5 KiB Raw Blame History