Stop Your Agent Fleet From Burning the Token Budget: subagent-budget-team

I measured something uncomfortable a while back: subagents burn roughly
48% of an agent's total token budget. I wrote subagent-tax as a
personal audit lens — run it after the fact, see where the tokens went.

That answers "where did the money go?" It doesn't answer "how do I stop
it next time?" — especially when it's not one agent but a fleet: a CI
matrix, several coding agents working in parallel, a team sharing one
token pool. For that you need a control plane, not an audit report. So I
built one.

What it is

subagent-budget-team is a zero-dependency Python CLI for team/CI
subagent budget control:

• Budget pools — one shared pot per CI job, team, or project
• Per-agent quotas — cap what each agent may spend inside the pool
• Overspend detection — check exits 1 when anything is over budget, so you can gate a pipeline on it
• Kill switch — kill freezes a pool (or a single agent) before the next spend happens; new spend is rejected immediately

pip install subagent-budget-team

# a $25 pool for the nightly CI run
subagent-budget-team pool create --name ci-nightly --limit-usd 25

# per-agent quotas inside the pool
subagent-budget-team quota set --pool ci-nightly --agent coder-1 --limit-usd 5

# agents record spend as they work
subagent-budget-team spend --pool ci-nightly --agent coder-1 \
  --tokens 12000 --usd 1.20

# gate your CI on this — exit 1 means over budget
subagent-budget-team check

# something's wrong? freeze it now, investigate later
subagent-budget-team kill --pool ci-nightly
subagent-budget-team release --pool ci-nightly   # unfreeze when ready

Why not the alternatives

vs subagent-tax (my earlier tool): that one is the personal audit
view — it tells you how much of your budget subagents consumed after
the fact. subagent-budget-team is the team/CI control view: a shared
budget pool with per-agent quotas and a circuit breaker, built for many
agents spending from one pot.

vs cloud-vendor budget alerts: those are post-hoc alarms. You get
paged after the money is spent. This is a pre-spend circuit breaker:
kill rejects new spend the moment you engage it, and check can fail a
pipeline before the next batch of work even starts.

A CI recipe

- run: pip install subagent-budget-team
- run: subagent-budget-team pool create --name pr-${{ github.event.number }} --limit-usd 10
- run: ./run-agents.sh   # agents call `spend` as they work
- run: subagent-budget-team check   # fails the job on overspend
- if: failure()
  run: subagent-budget-team kill --pool pr-${{ github.event.number }}

State is a plain JSON file (~/.subagent-budget-team/budgets.json,
overridable with --state or SBT_HOME), so each CI job gets an
isolated budget by pointing at its own file.

Links

• GitHub: https://github.com/hahahahahahahahah6/subagent-budget-team
• PyPI: https://pypi.org/project/subagent-budget-team/
• pip install subagent-budget-team — Python 3.9+, stdlib only, MIT licensed

Comments

[Launch Gate]

Where does the provider call sit relative to spend? In the recipe, check runs after the agents, so that path detects an overrun rather than preventing the charge. A two-worker example would clarify the circuit-breaker claim: both see $1 remaining and each starts a $0.75 request. Do they atomically reserve budget before either request starts, then reconcile actual usage, or record it afterward? I'd also show what kill means for requests already in flight, since rejecting the next ledger write cannot undo those charges.