Set Up Shell Hooks — Custom Event Callbacks
Register shell scripts as callbacks for Hermes events — block dangerous commands, auto-format files, inject context, and log activity.
Shell hooks let you run custom scripts when specific events occur in Hermes. Block dangerous commands before execution, auto-format files after writes, inject custom context before LLM calls, or log all activity. It's the escape hatch for custom behavior.
Managed cloud · API costs included · Skill library · Cancel anytime
Before you start:
- ☑Hermes Agent installed
- ☑Basic shell scripting knowledge
- ☑Understanding of JSON input/output
Steps
- 1
Understand hook events
Events: pre_tool_call, post_tool_call, pre_llm_call, post_llm_call, on_session_start, on_session_end, subagent_stop
- 2
Create a hook script
Write a shell script that reads JSON from stdin and outputs JSON to stdout
- 3
Add the hook to config.yaml
Under hooks:, add entries for each event with command and optional matcher
- 4
Set a timeout
Add timeout: 10 to prevent slow hooks from blocking the agent
- 5
Test the hook
Run a command that triggers the event and verify your script runs
- 6
Enable auto-accept (optional)
Set hooks_auto_accept: true to skip consent prompts for non-interactive runs
Pro Tips
- 💡Hooks receive JSON on stdin with event details — use jq to parse in bash scripts
- 💡Return {"block": true, "message": "reason"} from pre_tool_call to block the operation
- 💡Use matcher: 'terminal|write_file' to only trigger on specific tools
- 💡Each hook prompts for consent on first use — approve once and it's stored in ~/.hermes/shell-hooks-allowlist.json
Troubleshooting
❌ Hook script not executing
✅ Ensure the script is executable: chmod +x ~/.hermes/agent-hooks/my-hook.sh
❌ Hook blocks all commands unexpectedly
✅ Check your script's JSON output. Return empty {} to allow, or {"block": true} to block.
❌ Consent prompt every time
✅ After approving, the allowlist is stored in ~/.hermes/shell-hooks-allowlist.json. Check file permissions.
❌ Hook timeout causing delays
✅ Reduce timeout: to a smaller value or optimize your script. Slow hooks block the agent.