agent-cap

One dollar ceiling across the coding agents on your machine. Set it once; when Claude Code, Codex and Gemini CLI together reach it, their next tool call stops, with a message that names the ceiling and the one command that raises it.

npx --allow-git=root github:agentwares/agent-cap set 40/day

Also set 250/week or set 5/run (one agent session). Then:

npx --allow-git=root github:agentwares/agent-cap status   # spent, left, pace, when it runs out, per harness
npx --allow-git=root github:agentwares/agent-cap demo     # the whole loop on synthetic history
npx --allow-git=root github:agentwares/agent-cap off      # remove the ceiling and its hooks

Free and open source (MIT). Local: no account, no network requests, no LLM calls, no telemetry. The page: agentwares-agentguard.vercel.app/agent-cap.

What is enforced where

The ceiling is enforced through each harness's pre-tool-use hook (okgate's hook mode), written at user level so it covers every project. Where there is no hook of ours, agent-cap only warns.

Harness	Spend counted	At the ceiling
Claude Code	yes, from ~/.claude/projects (seatledger's reader)	halted: PreToolUse hook in ~/.claude/settings.json
Codex	yes, from ~/.codex/sessions (seatledger's reader)	halted: PreToolUse hook in ~/.codex/hooks.json, once you trust it in Codex's /hooks
Gemini CLI	no: seatledger has no Gemini CLI reader or Gemini prices yet	halted: BeforeTool hook in ~/.gemini/settings.json (to Gemini CLI's hook docs; not yet run live)
Cursor	no: Cursor keeps its usage on its servers	advisory only: a loud line in status and a desktop notification; agent-cap writes no Cursor hook

• Gemini CLI is stopped when the machine's total reaches the ceiling, but its own spend is not in that total yet.
• Cursor can run Claude Code's hooks (its third-party hooks setting), so the Claude Code hook may stop Cursor's agent too. That is untested, so Cursor is counted as not stopped, and status says so when the ceiling is reached.
• A harness that is not on the machine is named and skipped; run set again after installing it. A hook that goes missing, or that points at a file that no longer exists, turns its row to advisory in status.
• Hooks are read when a session starts: start a new session after set.

The hook never answers "allow": under the ceiling it prints nothing, so the agent's own permission prompts (and any okgate rules) decide as before.

The runaway guard

If 25% of the daily ceiling is spent inside 10 minutes, the hooked agents stop and stay stopped until a person runs resume (or sets the ceiling again): the pattern of an agent re-sending its whole context in a loop. Change it with set 40/day --runaway 50% --window 5. Under /week the daily ceiling is a seventh of the week's.

The kill switch

okgate's kill switch halts every hooked call, whatever the ceiling, checked before anything else: OKGATE_KILL=1 or AGENTGUARD_KILL=1 in the agent's environment, or a KILL file in .okgate/ or .agentguard/ in the project or in your home (okgate kill writes one). Every halt, of any kind, is appended to okgate's hash-chained audit log: the project's when it has an okgate.yaml, else ~/.okgate/audit.jsonl. An agent that tries to change its own ceiling (agent-cap set|off|resume, or a write into ~/.agent-cap) is refused; you change it in your own terminal, or in Claude Code with ! npx --allow-git=root github:agentwares/agent-cap set 60/day.

Recorded run

agent-cap demo on synthetic history (seatledger's generated Claude Code and Codex transcripts, not anyone's usage) in a temporary home that also has Gemini CLI and Cursor in it, with the clock pinned, under TZ=UTC. The hook calls are run in-process exactly as the harnesses run them.

# synthetic history: seatledger's generated Claude Code and Codex transcripts (not anyone's
# usage), in a temporary home that also has Gemini CLI and Cursor. Clock: 2026-10-07T16:00:00.000Z.

$ agent-cap set 70/day
ceiling   $70.00/day, API-equivalent USD at list prices, for every coding agent on this machine
runaway   halts above $17.50 inside 10 min (25% of the daily ceiling)
Claude Code added PreToolUse hook in ~/.claude/settings.json
Codex       added PreToolUse hook in ~/.codex/hooks.json
Gemini CLI  added BeforeTool hook in ~/.gemini/settings.json
Cursor      advisory only: no Cursor hook written; Cursor may also run Claude Code's hook, untested

Next: start a new session in each agent (hooks are read when a session starts).
      In Codex, trust the agent-cap hook once in /hooks; until then Codex skips it.
      npx --allow-git=root github:agentwares/agent-cap status     how much is left, per harness
      npx --allow-git=root github:agentwares/agent-cap off        remove the ceiling and the hooks

$ agent-cap status
agent-cap — $70.00/day ceiling (Wed 7 Oct, local day, resets Thu 00:00)

  spent       $31.25 of $70.00  (45%)
  remaining   $38.75
  pace        $0.00/hour over the last hour
  ceiling at  not before it resets, at this pace
  runaway     last 10 min $0.00, busiest 10 min $4.73; halts above $17.50 (25% of the daily ceiling)

  harness      spent         at the ceiling
  Claude Code  $29.82        halted (PreToolUse hook, ~/.claude/settings.json)
  Codex        $1.43         halted (PreToolUse hook, ~/.codex/hooks.json; trust it once in Codex's /hooks)
  Gemini CLI   not measured  halted (BeforeTool hook, ~/.gemini/settings.json; per Gemini CLI's hook docs, not yet run on a live Gemini CLI)
  Cursor       not measured  advisory, not stopped (no Cursor hook written; Cursor may also run Claude Code's hook, untested)

  USD at API list prices from seatledger's table (Anthropic read 2026-10-07, OpenAI read 2026-10-07); subscription seats are priced as if on the API.

See every teammate's Claude Code and Codex spend in one ledger, with history: seatledger Team https://agentwares-agentcheck.vercel.app/seatledger?ref=agent-cap

[hook] under the ceiling: Claude Code is about to run `npm test`
       allowed: the hook prints nothing; Claude Code's own permission flow decides

# 425 seconds later: one session re-sent a 180k-token context 21 times ($19.40).

[hook] a runaway burst: Claude Code is about to run `npm test`
       DENIED CAP_EXCEEDED: agent-cap's runaway guard: $19.40 was spent in 10 minutes, more than 25% of the daily ceiling ($17.50 of $70.00/day). Tool calls are halted until a person resumes.
       the person sees: agent-cap halted Bash: runaway guard, $19.40 in 10 min. Resume: npx --allow-git=root github:agentwares/agent-cap resume

[hook] the agent tries to lift its own halt: Claude Code is about to run `npx --allow-git=root github:agentwares/agent-cap resume`
       DENIED TOOL_DENIED: the spend ceiling is changed by a person, not by the agent it limits
       the person sees: agent-cap refused Bash: an agent may not change its own ceiling

# 11 minutes later the person resumes, in their own terminal:

$ agent-cap resume
agent-cap: released the runaway halt of 16:07 ($19.40 in 10 min). The ceiling still applies; check it with: npx --allow-git=root github:agentwares/agent-cap status

[hook] after resume: Claude Code is about to run `npm test`
       allowed: the hook prints nothing; Claude Code's own permission flow decides

# the person lowers the ceiling below what is already spent:

$ agent-cap set 50/day
ceiling   $50.00/day (was $70.00/day), API-equivalent USD at list prices, for every coding agent on this machine
runaway   halts above $12.50 inside 10 min (25% of the daily ceiling)
Cursor      advisory only: no Cursor hook written; Cursor may also run Claude Code's hook, untested
hooks       already in place: Claude Code, Codex, Gemini CLI

[hook] at the ceiling: Claude Code is about to run `npm test`
       DENIED CAP_EXCEEDED: agent-cap: the coding agents on this machine have spent $50.65 of the $50.00/day ceiling (API-equivalent USD at list prices). Tool calls are halted until the day resets (00:00).
       the person sees: agent-cap halted Bash: $50.65 of $50.00/day spent. Raise it: npx --allow-git=root github:agentwares/agent-cap set 75/day

$ agent-cap status
agent-cap — $50.00/day ceiling (Wed 7 Oct, local day, resets Thu 00:00)

!! CEILING REACHED: $50.65 of $50.00/day. Hooked agents are halted.
!! Cursor is NOT stopped by agent-cap: stop it yourself.

  spent       $50.65 of $50.00  (101%)
  remaining   $0.00
  pace        $19.40/hour over the last hour
  ceiling at  reached
  runaway     last 10 min $0.00, busiest 10 min $19.40; halts above $12.50 (25% of the daily ceiling)

  harness      spent         at the ceiling
  Claude Code  $49.22        halted (PreToolUse hook, ~/.claude/settings.json)
  Codex        $1.43         halted (PreToolUse hook, ~/.codex/hooks.json; trust it once in Codex's /hooks)
  Gemini CLI   not measured  halted (BeforeTool hook, ~/.gemini/settings.json; per Gemini CLI's hook docs, not yet run on a live Gemini CLI)
  Cursor       not measured  advisory, not stopped (no Cursor hook written; Cursor may also run Claude Code's hook, untested)

  USD at API list prices from seatledger's table (Anthropic read 2026-10-07, OpenAI read 2026-10-07); subscription seats are priced as if on the API.

See every teammate's Claude Code and Codex spend in one ledger, with history: seatledger Team https://agentwares-agentcheck.vercel.app/seatledger?ref=agent-cap

# and raises it again:

$ agent-cap set 80/day
ceiling   $80.00/day (was $50.00/day), API-equivalent USD at list prices, for every coding agent on this machine
runaway   halts above $20.00 inside 10 min (25% of the daily ceiling)
Cursor      advisory only: no Cursor hook written; Cursor may also run Claude Code's hook, untested
hooks       already in place: Claude Code, Codex, Gemini CLI

[hook] after raising it: Claude Code is about to run `npm test`
       allowed: the hook prints nothing; Claude Code's own permission flow decides

# okgate's kill switch halts every hooked call, under either name:

[hook] OKGATE_KILL=1: Claude Code is about to run `npm test`
       DENIED KILLED: the kill switch is on (OKGATE_KILL=1, env); every tool call is halted
       the person sees: agent-cap halted Bash: the kill switch is on (OKGATE_KILL=1)

[hook] AGENTGUARD_KILL=1: Claude Code is about to run `npm test`
       DENIED KILLED: the kill switch is on (AGENTGUARD_KILL=1, env); every tool call is halted
       the person sees: agent-cap halted Bash: the kill switch is on (AGENTGUARD_KILL=1)

# okgate's audit log ~/.okgate/audit.jsonl: 5 halts recorded, hash chain intact.
# desktop notifications raised: "agent-cap: runaway halted", "agent-cap: ceiling reached".

$ agent-cap off
removed   the ceiling
removed   agent-cap's hook from ~/.claude/settings.json
removed   agent-cap's hook from ~/.codex/hooks.json
removed   agent-cap's hook from ~/.gemini/settings.json

Where the dollar figures come from

Spend is read from Claude Code and Codex transcripts with seatledger's readers and priced per model at the API's list prices from seatledger's table, whose sources and the dates they were read are printed under every status. It is an API-equivalent figure: a subscription seat (Pro, Max, Plus) is priced as if its tokens had gone through the API, so on a plan it measures how hard the agents work, not your bill. Requests on a model with no list price are counted and left out of the total.

The day is your local day; the week runs from Monday 00:00 local; a run is one agent session counted over its last 24 hours. A hook reuses a measurement for up to 15 seconds (AGENT_CAP_REFRESH_S), so the ceiling can be passed by at most that much spend.

What it reads, writes and sends

• Reads token counts, model names, session ids and timestamps from ~/.claude/projects and ~/.codex/sessions (or $CLAUDE_CONFIG_DIR, $CODEX_HOME). Never prompt or response text, and no project names or paths in its output.
• Writes ~/.agent-cap (the ceiling, a small state file, a cache of counts per transcript, and when run through npx a copy of itself in runtime/, so the hooks keep working after npm prunes its cache) and one hook entry in each harness's settings file, keeping everything else there and a one-time *.agent-cap-backup of the file. off removes its entries.
• Sends nothing. No network requests, no LLM calls, no telemetry, no account. A desktop notification is a local osascript (macOS) or notify-send (Linux); AGENT_CAP_NO_NOTIFY=1 turns it off.

Commands

set <amount>/<day|week|run> [--runaway 25%] [--window 10] [--no-hooks] [--command <cmd>]
status [--json] [--quiet]
watch [--every 60]
resume
off
demo
hook pre-tool-use --client claude|codex|gemini     (what the hooks run)

--command agent-cap makes the hooks run a globally installed agent-cap instead of the copy that set was run from.

Claude Code plugin

/plugin marketplace add agentwares/agent-cap
/plugin install agent-cap@agent-cap

/agent-cap:agent-cap runs npx -y --allow-git=root github:agentwares/agent-cap status --json and explains it. It never sets or raises the ceiling.

For a team

See every teammate's Claude Code and Codex spend in one ledger, with history: seatledger Team, https://agentwares-agentcheck.vercel.app/seatledger?ref=agent-cap. One budget across a team, with alerts, is not built; the page has a button that counts who wants it.

MIT © agentwares contributors.