agent-budget

Real-time cost and token budget enforcer for Claude agent sessions. A drop-in proxy that sits between your code and Anthropic's API — set hard dollar caps per budget, auto-block requests before overruns, and get webhook alerts with spend breakdowns.

How It Works

1. Point your Anthropic SDK's base_url at this proxy
2. Tag each request with an X-Budget-Id header
3. The proxy enforces spend limits, tracks token usage, and fires alerts at 50%/80%/100% thresholds

Unlike passive cost trackers, agent-budget blocks the request before the money is spent.

Data Sources

| Source | URL / Mechanism | Refresh |
|---|---|---|
| Anthropic Messages API | https://api.anthropic.com/v1/messages (proxied) | Every proxied request |
| Anthropic response usage block | Parsed from each proxy response body | Every proxied request |
| Model pricing | Seeded from Anthropic pricing; editable via API | Static config, user-updatable |

No external feeds are scraped. All cost data is generated from real API traffic flowing through the proxy.

API Endpoints

| Method | Path | Description |
|---|---|---|
| GET | /agent-budget/health | Health check → { ok: true } |
| POST | /agent-budget/v1/messages | Core proxy — forwards to Anthropic with budget enforcement |
| GET | /agent-budget/api/budgets | List all budgets with current spend |
| POST | /agent-budget/api/budgets | Create budget: { name, max_dollars, period?, webhook_url? } |
| GET | /agent-budget/api/budgets/:id | Budget detail with model breakdown |
| DELETE | /agent-budget/api/budgets/:id | Delete budget and usage records |
| GET | /agent-budget/api/budgets/:id/usage | Paginated usage records (?limit=50&offset=0) |
| GET | /agent-budget/api/budgets/:id/badge | SVG status badge (embeddable) |
| POST | /agent-budget/api/budgets/:id/test-webhook | Test webhook delivery |
| GET | /agent-budget/api/alerts | Recent alerts across all budgets |
| GET | /agent-budget/api/pricing | Current model pricing table |
| PUT | /agent-budget/api/pricing | Update pricing for a model |
| GET | /agent-budget/api/stats | Aggregate stats |

Running Locally

# Install
npm install

# Start (default port 4727)
node server.js

# Or with custom port
PORT=4727 node server.js
```

Open http://localhost:4727/agent-budget/ for the dashboard.

Quick Start

1. Create a budget

curl -X POST http://localhost:4727/agent-budget/api/budgets \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agents","max_dollars":25,"period":"daily"}'

2. Point your SDK at the proxy

from anthropic import Anthropic

client = Anthropic(base_url="http://localhost:4727/agent-budget")

response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}],
extra_headers={"X-Budget-Id": "my-agents"},
)
```

3. Embed a badge

![Budget](http://localhost:4727/agent-budget/api/budgets/1/badge)

Cron Jobs

| Schedule | Task |
|---|---|
| Every hour | Delete usage records older than 90 days |

Limitations

• Streaming (stream: true) is not supported — proxy returns 400
• No authentication — all endpoints are public
• Single-instance deployment (no multi-tenancy)

Stack

Node.js, Express, better-sqlite3 (WAL mode), node-cron, helmet, compression