ccam-cost-guard — Claude Code hook: session spend alerts and forecasts
ccam-cost-guard tracks Claude Code spending and posts session stop events directly to the local Agent Monitor dashboard.
MIT ★ 1,198 updated 2026-10-23
/plugin marketplace add hoangsonww/Claude-Code-Agent-Monitor
/plugin install ccam-cost-guard@claude-code-agent-monitor-pluginsWhat ccam-cost-guard does
This hook executes whenever Claude Code reaches a Stop event. It extracts the session identifier, the stop reason, and an ISO timestamp using jq. Next, it dispatches this JSON payload to http://localhost:4820/api/hooks/event using curl. Network errors fail silently by design.
The Agent Monitor pricing engine reads these events to monitor spend against a target budget. It projects end-of-month costs from daily trends and identifies the most expensive sessions. The engine also calculates potential savings from routing prompts to cheaper models and configures threshold alert triggers.
Both jq and curl must exist in your environment path. Without a live Agent Monitor service listening on port 4820, the hook silently drops the dispatched metrics.
What it helps with
- Track Claude Code API spend against a set target budget
- Project month-end expenses based on daily usage trends
- Pinpoint the most expensive agent sessions
- Estimate potential savings from routing tasks to cheaper models
- Trigger alerts when spending exceeds defined thresholds
Example prompts for the agent
- Finish the refactor and stop the current session
- Stop the task and print a summary of changes
How to install ccam-cost-guard
1Plugin marketplace
/plugin marketplace add hoangsonww/Claude-Code-Agent-Monitor/plugin install ccam-cost-guard@claude-code-agent-monitor-plugins2Manually: put the files in place
.claude/settings.jsonThe hooks block: event (PreToolUse, PostToolUse, Stop…) → command. Personal ones go to ~/.claude/settings.json
Step by step, with commands for each platform: Claude Code hooks: what they are, where to configure them, how to block a risky command
Questions about ccam-cost-guard
How to install ccam-cost-guard in Claude Code?
Run /plugin marketplace add hoangsonww/Claude-Code-Agent-Monitor to register the marketplace, then execute /plugin install ccam-cost-guard@claude-code-agent-monitor-plugins. You can also configure it in .claude/settings.json.
What does ccam-cost-guard do?
It listens for Stop events in Claude Code and transmits session metadata to Agent Monitor. The backend tracks expenses, estimates savings, and flags budget threshold breaches.
What prerequisites are needed for this hook?
Your system needs jq and curl installed, plus an active Agent Monitor server running at http://localhost:4820. If the dashboard is offline, the hook fails silently.
Source text
hooks.json · MIT
Hooks bundle shipped with the ccam-cost-guard plugin for Claude Code.
Budget tracking, spend forecasting, and cost-threshold alerts for Claude Code usage via the Agent Monitor pricing engine. Watches spend against a target budget, projects month-end cost from the daily trend, surfaces the priciest sessions, estimates savings from cheaper-model routing, and wires up cost alert rules — all backed by the dashboard at http://localhost:4820.
Triggers on: Stop.
```json
{
"hooks": {
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "jq -c '{event_type: \"Stop\", session_id: .session_id, stop_reason: .stop_reason, timestamp: (now | todate)}' 2>/dev/null | curl -s -X POST http://localhost:4820/api/hooks/event -H 'Content-Type: application/json' -d @- > /dev/null 2>&1 || true"
}
]
}
]
}
}
```
© Son Nguyen · MIT · hoangsonww/Claude-Code-Agent-Monitor