Claude Code's native Auto Mode (
"defaultMode": "auto") now performs the same job — model-side safety checks that auto-approve commands aligned with the user's request, surfacing only the ones that need human judgment. Codex shipped an equivalent native classifier.If you've adopted Auto Mode, this hook is largely redundant — you'll be paying for two classifiers (Anthropic's internal one + OpenRouter Haiku) and they can disagree on edge cases. The repo stays available for users who prefer explicit rule-based gating with a custom config and audit log, but new features are no longer planned.
Anyone who uses Claude Code heavily eventually gets tired of approving harmless commands. Most people start by adding allow-list exceptions, and some end up switching on --dangerously-skip-permissions. The incident reports linked below are a good reminder of why that trade-off is risky.
The idea in this repo is simple: keep rules for obviously safe commands, and use a small, fast model such as Haiku for the harder cases. In practice, that means most routine commands are approved automatically, while the user only sees the commands that look dangerous or unclear.
Technically, this is a Claude Code hook that classifies the full Bash command by risk. By default, the LLM step runs through OpenRouter.
On current OpenRouter pricing this is usually a cents-per-day tool, not a dollars-per-day one. The rough math is in SETUP.md.
| Risk | Behavior |
|---|---|
none / low |
allow silently |
medium |
ask Haiku for a yes/no decision in context |
high / critical |
always show a dialog |
Real-world cases where AI agents ran rm -rf, git reset --hard, and similar commands through over-broad allow-list rules are collected in INCIDENTS.md.
- Match known command shapes with regex rules.
- Keep interpreter wrappers such as
python -c,bash -c, andpowershell -Commandat leastmedium. - Use Haiku for medium-risk or novel cases, with the command, current working directory, and optional project-specific config.
- Cache decisions by full command plus
cwd.
If the OpenRouter key is missing, the network fails, or the model call errors out, medium-risk commands fall back to a dialog instead of silent allow. On Windows a MessageBox is shown once to explain why. High and critical commands never bypass the dialog.
See SETUP.md for the full walkthrough. The short version is:
- Copy
hook/haiku_guard.pyto~/.claude/hooks/haiku_guard.py. - Put your OpenRouter key (
sk-or-...) in~/.openrouter_key. - Merge the
PreToolUsehook from examples/settings.json into~/.claude/settings.json. - Remove broad
Bash(<something> *)entries from your allow-list. - Restart Claude Code.
Optional config lives at ~/.claude/hooks/haiku_guard.config.json:
{
"critical_files": ["CLAUDE.md", "*.csproj", "MyProject.sln"],
"critical_dirs": [".claude/", "src/core/", "migrations/"],
"development_processes": ["dotnet", "node", "python"]
}Missing fields fall back to DEFAULT_CONFIG in hook/haiku_guard.py.
Environment variables:
HAIKU_GUARD_OPENROUTER_KEYHAIKU_GUARD_OPENROUTER_KEY_FILEHAIKU_GUARD_MODELHAIKU_GUARD_TIMEOUT
The default model is anthropic/claude-haiku-4.5. You can point HAIKU_GUARD_MODEL at another OpenRouter model, but only the default has been exercised so far. If you switch models, rerun the Haiku-backed tests first.
cd tests
python test_classifier.py
python test_haiku_decision.py
python test_interpreter_destructive.pytest_classifier.py is fully offline. The two Haiku-backed suites require an OpenRouter key and skip cleanly when no key is configured.
- The rules and examples are tuned for Windows and Git Bash.
- The hook contract is specific to Claude Code.
- Medium-risk decisions depend on OpenRouter. Without a key, they fall back to a dialog.
- Broad Bash allow rules in Claude settings still defeat the point of this guard, so keep them out of both global and project settings.
- Cache entries are scoped to the full command and
cwd, so the same command in another directory is evaluated again.
- dwarvesf/claude-guardrails — guardrails for Claude Code via hooks
- lasso-security/claude-hooks — security hooks pack from Lasso Security
- disler/claude-code-hooks-multi-agent-observability — multi-agent observability via hooks
- shaominngqing/bark-claude-code-hook — Bark-based voice notifications hook
- chainguard-dev/multiclaude — Chainguard wrapper around Claude Code
MIT