AgentCap
Stop Claude Code and Codex runs that loop or eat your weekly quota. AgentCap stops a run
that repeats the same tool call or keeps failing, and stops a job at its share of your
Claude Max/Pro or ChatGPT weekly / 5-hour quota, with an evidence receipt of why. Free
agentcap waste shows where your tokens already went: subagents, Opus, cache misses,
tool loops and error streaks.
$ agentcap waste --since 7d
SUBAGENTS $41.20 25% of spend in 31 subagent/forked threads
OPUS $38.90 24% of spend
CACHE MISSES $6.10 57 cache re-writes after the TTL ran out (5 min since the last request, or 1 h)
main session $2.30 21x subagents $3.80 36x
Tip: idle subagents re-wrote their own context 36x (~$3.80). Set subagentPromptCacheTtl: "1h" ...
STARTING CONTEXT 31 subagents, first request median 38.2k tok, largest 131.0k (7f3a91c2/a1b2c3d4)
REPEATED TOOL CALLS $9.80 12 streaks of >= 3 identical calls in a row
TOOL ERROR STREAKS $4.30 5 streaks of >= 3 failing calls in a row
Pro would have stopped this run at $3.12 / at 4 repeats (Bash x11 in 7f3a91c2, $2.40 after that).
(illustrative numbers; run it on your own logs, it is read-only)
Stop loops and quota burn (Pro)
agentcap run --quota 5% -- claude # subscription: stop at 5% of the weekly quota, or on a loop
agentcap run --quota 10% --window 5h -- codex # same for Codex on a ChatGPT plan
agentcap run --cap 2 -- codex exec "fix tests" # API key: $2 cap + loop/burn breaker
agentcap approve # raise a stopped job's limit by 50% (at most twice)
On a $20/month Codex plan, two code-review prompts used the whole 5-hour limit
(Povilas Korop: $7.70 + $1.43 at API prices).
--quota 10% --window 5h -- codex stops the job before that.
Free tools like claude-code-spend-stop and
RelayPlane give you a free $ cap. AgentCap adds the loop breaker, a cap on
your subscription quota % and Codex support.
- Loop breaker. Same tool call (name + input) 4 times in a row, or 8 failing tool calls in a
row: the run is stopped (exit 4). On subscriptions it works without touching your login or
traffic: Claude Code via an official
PreToolUse hook (denies the 4th identical call and ends
the turn; an interactive session stays open so you can agentcap approve or quit; headless
claude -p runs get SIGINT if they keep going); Codex by reading its own rollout file (SIGINT). On API keys the
proxy also catches identical requests and --max-burn $/min spikes.
- Per-job quota %. Stop one job at its share of the account's weekly or 5-hour limit.
- Evidence receipt. Each stop prints and saves why (
same tool call 4 times in a row (Bash),
the account's weekly quota rose 5.1% while this job ran) and the last tool call's name, as numbers and tool
names only, never prompts or tool inputs.
- Approve. After a stop,
agentcap approve (or /agentcap:approve in the plugin) raises the
limit by 50%, at most twice, and the run continues. This works for interactive Claude Code,
which stays open after a stop. Codex and headless claude -p jobs are stopped with SIGINT, so
there approve only helps before the limit is hit; after a stop it says so and changes nothing.
Run it from your own shell while the job runs (live Codex test: 1% -> 1.5% -> 2.25%, the third
approve refused). With whole-percent quota steps a 1.5% limit stops at the next step, 2%.
- Free runs the same detectors in observe-only mode and prints what Pro would have done.
Honest limits: Claude tool-error streaks are only caught on API-key runs (the subscription hook sees
the call, not its result); the stop can be one request late; quota % is account-level; verified on
fixtures, fake CLIs and real Claude Code hooks; quota stops verified on real Claude Pro and ChatGPT
Plus accounts (see "Supported & tested").
The API-key cap
AgentCap runs
the CLI behind a local proxy on 127.0.0.1 and applies a local spend cap to the
run. Before each request it reserves the worst-case cost; when the budget is gone
it kills the local process and tells you why. No dashboard, no account, no code
changes for tools that honour a base-URL environment variable.
Claude Code and Codex CLI are routed automatically (Gemini CLI too). AgentCap meters API-key
traffic — POST /v1/responses and /v1/chat/completions (Codex CLI uses the
Responses API) plus Gemini generateContent / streamGenerateContent and Anthropic POST /v1/messages. ChatGPT
or Google sign-in (OAuth/subscription) traffic is not metered.
What it is
AgentCap is a small, local, serverless spend-cap proxy. You give it a command
and a cap:
agentcap run --cap 2 -- codex exec "fix the failing tests"
Everything the child sends to OpenAI or Gemini is routed through a proxy on
127.0.0.1. AgentCap reserves the worst-case cost of each request before it is
forwarded, settles the real usage afterwards, and terminates the agent's process
group if the cap would be exceeded. This is a local spend cap, not a
mathematical guarantee: with conservative reservation it reserves worst-case
cost before each request, so overshoot is rare but possible when providers count
more tokens than estimated.
Simulated demo — fake local API, no key, no money.
Install
The package is published on PyPI as agentcap-cli (the name agentcap is
taken), but the command it installs is still agentcap.
# install the command globally
pipx install agentcap-cli
# or into the current environment
pip install agentcap-cli
This is the beginning of the README. Read the rest at the original. Read the full README ↗
