AgentCap — a hard dollar cap for Claude Code sessions

The problem

Account limits don't stop one session.

Developers running autonomous coding agents (Claude Code, Codex, custom agent loops) have no way to cap spend per-session or per-task in real time — only account-wide limits exist today. Multiple independent developers have posted real losses ($32 to $2,847) from runaway/looping agents in the last few months, and at least a dozen scrappy, low-traction open-source tools have been built to solve this same narrow problem — evidence of real, current, unmet pain with no dominant solution yet.

$2,847

Largest reported loss · smallest: $32

One command

Warn at 80%. Stop at 100%.

80%

A warning

A desktop notification and a terminal warning, while there's still room to steer.

100%

A hard stop

The agent process is terminated. Tool calls are denied the instant the cap trips, so it can't fire one more on its way out.

.db

A local log

Every session is written to a local SQLite file you own. Check it any time with agentcap status.

Desktop notifications

You hear about it before the bill does.

Real notifications from real sessions: one at 80%, one when the cap stops the agent.

Three macOS notifications from AgentCap: 80% of cap used at $0.25 of $0.30, and two cap-reached alerts stopping the session at $0.31 of $0.30 and $1.02 of $1.00.

A cap is required. There is no implicit default, because an unbounded session is the exact thing this tool exists to prevent.

Install

Running in under 5 minutes.

Install globally

npm install -g agentcap

Or run it without installing

npx agentcap run --cap 5.00 -- claude

Requires Node 18.17+

If you get agentcap: command not found after installing

This almost always means npm's global bin directory isn't on your shell's PATH. It's common with nvm, whose setup usually lives in .zshrc — so if your login shell is bash (or you have no bash dotfiles), the shell never loads nvm and never sees agentcap, npm, or even node.

Check where npm installed it and whether your shell can see that directory:

npm prefix -g              # npm's global bin lives in <prefix>/bin
echo $PATH

The most reliable fix is a small launcher in a directory that's always on PATH, which calls node by absolute path instead of relying on #!/usr/bin/env node:

printf '#!/bin/sh\nexec "%s" "%s" "$@"\n' "$(command -v node)" "$(npm prefix -g)/lib/node_modules/agentcap/bin/agentcap.js" \
  > /usr/local/bin/agentcap && chmod +x /usr/local/bin/agentcap

AgentCap also resolves the agent binary the same way — it checks ~/.local/bin, ~/bin, ~/.claude/local, /usr/local/bin, and /opt/homebrew/bin before giving up, so -- claude keeps working even when Claude Code isn't on your PATH.

Usage

# Wrap a normal interactive Claude Code session with a $5 cap
agentcap run --cap 5.00 -- claude

# `claude` is the default, so this is the same thing
agentcap run --cap 5.00

# Any Claude Code flags pass straight through
agentcap run --cap 10 -- claude --model opus --resume

# What have I spent today?
agentcap status

agentcap status

agentcap status  2026-08-23
  STARTED  SPEND      CAP       STATUS     PROJECT
  09:14    $1.82      $5.00     done       ~/code/api
  11:02    $5.01      $5.00     capped     ~/code/webapp
  today  $6.83  across 2 sessions

0normal

2stopped by cap

3tracking failure

64bad usage

How it works

Priced from the transcript.

Claude Code's hook payloads contain no token or cost data — that was the first thing we checked, across all 31 hook events. What every hook payload does contain is transcript_path, and Claude Code's own transcript records the full Anthropic usage object and model for every request it makes.

PieceRole

Hooks (--settings) Report the authoritative transcript path, and act as the deny gate once the cap trips

Transcript (.jsonl) The source of truth for tokens; read incrementally, priced locally

Wrapper process Owns accounting, notifications, and terminating the agent

Hooks are injected via claude --settings '<json>', which merges with your existing config. AgentCap never writes to ~/.claude/settings.json or your project's .claude/settings.json, so there is nothing to clean up and nothing to corrupt if it dies unexpectedly.

Getting the number right

Harder than summing a column.

2.3×

Deduplicated by message.id

Claude Code writes one JSONL line per content block, each repeating the same usage object. Summing naively over-counted a real 10 MB transcript by 2.3× — which would make the hard stop fire less than halfway to your actual cap.

1.25× / 2×

Both cache-write tiers

5-minute writes cost 1.25× base input; 1-hour writes cost 2×. Claude Code leans heavily on 1-hour caching, so collapsing the two under-counts the single largest line item in a long session. AgentCap reads the TTL split separately.

Also counted Subagent (sidechain) usage Web search at $10/1k Fast-mode premium pricing 1.1× US data-residency

Failing loud

No silent protection.

A session it cannot measure is a session it cannot cap, and it says so rather than sitting there looking reassuring.

AgentCap prints a visible error and stops the session if:

01a model appears that it has no price for (a new Claude release) — it will never silently price an unknown model at $0

02the transcript cannot be read

03no hook fires within 30 seconds, meaning it cannot confirm it is tracking at all

04the wrapped command cannot be started

Get the source

The repo, in your inbox.

Enter your personal email, and we'll send you the GitHub link. We'll also write when a new version ships.

Note: For individuals only

One email with the link, then occasional release notes. Unsubscribe any time.

Licence

Free for your own work.

Source-available and entirely local. No account, no signup, no telemetry, no network calls.

Individuals

$0

Free for individuals on their own personal work.

How to Install AgentCap →

Companies & teams

Commercial

Company and team use needs a commercial licence.