My Subagents Were Eating 48% of My Tokens. So I Gave Them Hard Budget Caps — Enforced by Hooks, Not Dashboards
My subagents were eating 48% of my tokens. So I gave them hard budget caps — enforced by hooks, not dashboards A few weeks ago a measurement made the rounds: developer aidiveyt logged a month of Claude Code usage — 455 sessions, 2,631 subagent runs — and found subagents had consumed 48.1% of all tokens . The median subagent's first request alone was 47,117 tokens. Nobody approved that spend. It…
A recent report surfaced that developer aidiveyt had tracked Claude Code usage for a month and found that subagents had consumed 48.1% of all tokens. One subagent's initial request alone totaled 47,117 tokens, and this was happening quietly in the background, one Task call at a time. Many in the community echoed the sentiment that hard budget caps were needed.
Simon Willison, after experiencing the same problem, built a tool called subagent-budget. This tool enforces per-agent-type token and dollar budgets through Claude Code hooks, preventing over-budget subagents from launching. To set up budget caps, users install subagent-budget, initialize budgets with default token and USD limits, and then set specific budgets using patterns.
The enforcement is done by adding a block in the Claude settings file, which runs a budget check before every subagent launch. If the budget is exceeded, Claude returns an error indicating the type of budget that was exceeded. Unlike subagent-ledger, subagent-budget not only tracks token usage but also estimates costs in dollars, using built-in model price tables that can be overridden in the config.
It also maintains a cross-session ledger that survives session ends. The budget rules are matched using globs against the agent's description and subagent type, with the first match taking precedence. This tool works well with resume-budget-guard, and its budget rules can be easily imported. The enforcement is per-machine, and it is idempotent, meaning that re-running the tool will not change the outcome.
While the transcript backfill is estimated, users can provide exact figures using the record command with the --tokens flag.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
