Other tools show you the fire. claude-guard is the fire extinguisher.
Claude Code's built-in limits only warn. claude-guard blocks.
$ claude-guard status
claude-guard v0.1.0
Session $ 4.82 / $ 5.00 [████████████████████░] 96.4% ⚠ WARNING
Hourly $ 8.12 / $ 10.00 [████████████████░░░░░] 81.2% ⚠ WARNING
Daily $ 18.50 / $ 50.00 [███████░░░░░░░░░░░░░░] 37.0%
Monthly $142.30 / $500.00 [██████░░░░░░░░░░░░░░░] 28.5%
Status: DENY
⛔ Tool call BLOCKED — session budget exceeded
claude-guard is for developers running Claude Code with their own API key — not the Pro/Max subscription.
If you're on the $20/mo Pro or $100–200/mo Max plan, your costs are capped by the subscription. You don't need this.
But if you're using ANTHROPIC_API_KEY — because you hit subscription rate limits, your team runs Claude Code on company billing, you're using it in CI/CD, or you got pushed to API access — then every tool call is billed per token. And there's no hard spending cap.
| what happens | how much it costs | how long it takes |
|---|---|---|
| agent stuck in retry loop | $200–500 | 30 minutes |
| forgotten background session overnight | $1,000–2,000+ | 8 hours |
| recursive tool calls on large codebase | $50–150 | 10 minutes |
| normal day of heavy API-key usage | $20–80 | all day |
Claude Code has sessionLimit and dailyLimit in settings. They pop up a warning. Claude says "noted" and keeps spending.
There is no hard stop. There is no circuit breaker. There is no brake pedal.
Until now.
pip install claude-guard
claude-guard init # creates ~/.claude-guard.json with sane defaults
claude-guard install # hooks into Claude CodeDone. Every tool call now runs through a budget check first.
Claude Code claude-guard
─────────── ────────────
Tool Call ──→ PreToolUse Hook ──→ check budget
│
├─ OK (<80%) → allow ✅
├─ WARN (≥80%) → allow + warn ⚠️
├─ DENY (≥100%) → block tool ⛔
└─ KILL (≥150%) → terminate session 💀
After Call ──→ PostToolUse Hook ──→ log cost, update state
| window | default | what it catches |
|---|---|---|
| Session | $5.00 | single task going wild |
| Hourly | $10.00 | sustained expensive loops |
| Daily | $50.00 | all-day background agents |
| Monthly | $500.00 | slow cumulative bleed |
| threshold | action | result |
|---|---|---|
| < 80% | ✅ Allow | normal operation |
| ≥ 80% | system message injected to Claude | |
| ≥ 100% | ⛔ Deny | permissionDecision: "deny" — tool blocked |
| ≥ 150% | 💀 Kill | continue: false — session terminated |
Doesn't just watch totals — watches rate.
If your $/min spikes 3x above rolling average → alert fires before you hit the hard cap. Catches runaway loops in seconds, not minutes.
Hook performance on real workloads:
| metric | value |
|---|---|
| Budget check latency | < 10ms |
| State file read | < 2ms |
| Hook timeout limit | 5,000ms |
| Overhead per tool call | ~0.2% |
| False positive rate | 0% (math, not heuristics) |
| Test coverage | 67 tests, 5 test files |
| Dependencies | 0 (pure stdlib) |
| Lines of code | ~1,200 (excl. tests) |
| Supported platforms | Windows, macOS, Linux |
| feature | claude-guard | claude-hud | ccusage | cccost |
|---|---|---|---|---|
| prevents overspend | ✅ | ❌ | ❌ | ❌ |
| hard budget enforcement | ✅ | ❌ | ❌ | ❌ |
| auto-kill runaway sessions | ✅ | ❌ | ❌ | ❌ |
| anomaly / spike detection | ✅ | ❌ | ❌ | ❌ |
| real-time monitoring | ✅ | ✅ | ❌ | ✅ |
| session/hourly/daily/monthly | ✅ | ❌ | ✅ | ❌ |
| zero dependencies | ✅ | ❌ | ❌ | ✅ |
| claude code plugin | ✅ | ✅ | ❌ | ❌ |
| category | 🛡️ circuit breaker | 📊 dashboard | 📈 analyzer | 📝 logger |
speedometer vs brake pedal.
~/.claude-guard.json:
{
"budgets": {
"session": 5.00,
"hourly": 10.00,
"daily": 50.00,
"monthly": 500.00
},
"alerts": {
"warn_at_percent": 80,
"sound": true
},
"anomaly": {
"spike_multiplier": 3.0,
"lookback_window_minutes": 30
},
"action_on_limit": "deny",
"action_on_hard_limit": "kill"
}Or from CLI:
claude-guard set daily 25 # $25/day limit
claude-guard set session 10 # $10/session
claude-guard set monthly 200 # $200/month
claude-guard set hourly 0 # disable hourly limitclaude-guard init # create config with defaults
claude-guard status # live spend vs limits
claude-guard history # recent cost events
claude-guard set <session|hourly|daily|monthly> <amount>
claude-guard reset [session|daily|all] # reset counters
claude-guard watch # live monitor (foreground)
claude-guard install # add claude code plugin
claude-guard uninstall # remove plugincosts are calculated per-token using official Anthropic pricing:
| model | input | output | cache read | cache create |
|---|---|---|---|---|
| claude-opus-4-6 | $15.00/M | $75.00/M | $1.875/M | $18.75/M |
| claude-sonnet-4-6 | $3.00/M | $15.00/M | $0.375/M | $3.75/M |
| claude-haiku-4-5 | $0.80/M | $4.00/M | $0.08/M | $1.00/M |
unknown models default to sonnet pricing (conservative).
claude-guard/
├── claude_guard/
│ ├── config.py # budget limits, alert settings, anomaly config
│ ├── state.py # time-window cost aggregation, persistence
│ ├── engine.py # budget check logic, status decisions
│ ├── watcher.py # JSONL session file parser, cost calculator
│ ├── anomaly.py # rolling-window spike detection
│ └── cli.py # terminal UI, colored progress bars
├── hooks/
│ ├── pre_tool_use.py # the circuit breaker (deny/kill)
│ └── post_tool_use.py # cost logging after each tool
├── plugin.json # claude code plugin manifest
└── tests/ # 67 tests across 5 files
will this slow down claude code? no. budget check = read JSON + arithmetic. < 10ms. hook timeout is 5 seconds. you won't notice it.
what if i need to go over budget?
claude-guard set session 0 disables session limit. claude-guard reset session zeros the counter. your call.
does this work with the claude API directly? no. claude-guard is built for claude code — it monitors JSONL session files and uses the hook system. for direct API usage, set limits in the anthropic console.
can i use this with cursor / windsurf / other tools? currently claude code only. architecture is extensible. PRs welcome.
what python versions? 3.10, 3.11, 3.12. tested on all three across windows, macos, and linux via github actions.
PRs welcome. tests required.
git clone https://github.com/LuciferDono/claude-guard
cd claude-guard
pip install -e .
python -m pytest tests/ -v # 67 tests, ~2 seconds