Plugs into Claude Code's hooks system. Watches every tool call and subagent and stops failures before they burn your bill. Terminal CLI and desktop app. Two lines, no code changes.
pip install agentsonar
agentsonar install-claude-hooks
# or without agentsonar on PATH:
python -m agentsonar install-claude-hooks
Start a fresh Claude Code session after installing. No API keys, no config, no code changes — agentSonar is live.
Default is project-level. Click a scope to copy the right command.
Watches the shape of the traffic — which tool ran, when, whether it succeeded, how subagents fanned out. Tool inputs, outputs, prompts, and file contents are never read or logged.
Work bouncing between agents forever. Warns at 5 rotations, critical at 15.
The most common Claude Code failure. Same tool failing, agent keeps hammering. Warns at 2 errors, critical at 3.
Same tool, identical args — re-reading the same file 14,000 times was a real documented incident. Caught at repeat #3.
Runaway fan-out of subagents spawned at once. Each one bills you.
A tool or MCP server that starts and never returns. Warns at 120 s, critical at 300 s.
Sudden burst of tool calls way outside the session's normal rate.
Same agent, same request, same answer — over and over, no progress.
Session filling toward the model's context limit. Warns at 50%, critical at 75%.
A tool-call loop cost $437 overnight in one incident. A redundant-work storm fired 14,000 identical calls. agentSonar catches both in under a minute.
Detection tells you after. Prevent Mode stops the failure before the next tool call — add an env block to .claude/settings.json and relaunch.
{
"env": {
// arm a specific class:
"AGENTSONAR_PREVENT_CASCADE_FAILURE_MAX_ERRORS": "2",
// or everything at once:
"AGENTSONAR_PREVENT_ALL": "1",
// hard-block instead of prompt:
"AGENTSONAR_PREVENT_DECISION": "deny"
},
"hooks": { /* your hooks */ }
}
| Failure class | Env var |
|---|---|
| Retry storm | AGENTSONAR_PREVENT_CASCADE_FAILURE_MAX_ERRORS=2 |
| Silent loop | AGENTSONAR_PREVENT_CYCLE_MAX_ROTATIONS=5 |
| Redundant work | AGENTSONAR_PREVENT_REDUNDANT_WORK_MAX_REPEATS=3 |
| Subagent fan-out | AGENTSONAR_PREVENT_SUBAGENT_EXPLOSION_MAX_CONCURRENT=5 |
| Everything | AGENTSONAR_PREVENT_ALL=1 |
Default surface is ask (Claude Code shows an approve/deny prompt). Set AGENTSONAR_PREVENT_DECISION=deny to hard-block without prompting. Arm stays on for every session once set.
Reports live under ~/.agentsonar/, keyed by session id. The HTML report regenerates after every reply — always up to date.
~/.agentsonar/ ├── reports/ │ ├── latest │ └── <session-id>/ │ ├── report.html # open in browser │ ├── report.json # for CI / tickets │ └── alerts.log # plain-text stream └── sessions/ └── <session-id>/ └── timeline.jsonl # append-only events
agentsonar open # most recent agentsonar reports # list all sessions agentsonar open hidden-delta # by slug
Each session gets a short slug (like hidden-delta) so you can tell runs apart at a glance and reopen one without copying a UUID.
Make a detector fire in 60 seconds. Paste this into a Claude Code session with hooks installed — it reproduces the most common failure: a tool keeps failing and the agent keeps retrying.
Run `cat ./missing-config.json` four times as four separate Bash calls. Do not create the file. Run the exact same command each time.
Each cat exits with an error. agentSonar sees the same tool failing on the same edge and fires a cascade_failure alert.
agentsonar open
You'll see a cascade_failure CRITICAL card with the failing tool, the consecutive error count, and severity. No setup needed beyond the two install lines.
Prefer to wire it by hand? This is exactly what install-claude-hooks writes. Strict JSON — no comments, no trailing commas.
{
"hooks": {
"PreToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "python -m agentsonar claude-code-hook PreToolUse", "timeout": 60 }] }],
"PostToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "python -m agentsonar claude-code-hook PostToolUse", "timeout": 60 }] }],
"PostToolUseFailure": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "python -m agentsonar claude-code-hook PostToolUseFailure", "timeout": 60 }] }],
"Stop": [{ "hooks": [{ "type": "command", "command": "python -m agentsonar claude-code-hook Stop", "timeout": 60 }] }],
"SubagentStop": [{ "hooks": [{ "type": "command", "command": "python -m agentsonar claude-code-hook SubagentStop", "timeout": 60 }] }]
}
}
The installer writes exactly this — these five hooks are the minimal set agentSonar needs. PreToolUse stays synchronous (that's where Prevent Mode blocks). PostToolUse and PostToolUseFailure can be marked "async": true on newer Claude Code builds to run off the hot path.