Overview
hermes hooks inspects shell-script hooks declared in ~/.hermes/config.yaml, tests them against synthetic payloads, and manages the first-use consent allowlist at ~/.hermes/shell-hooks-allowlist.json.
hermes hooks <list|test|revoke|doctor>Aliases are accepted: ls for list, remove/rm for revoke.
Subcommands
list (or ls) — List configured hooks
hermes hooks list
hermes hooks lsShows each hook’s matcher, timeout, and consent status.
test — Fire matching hooks against a synthetic payload
hermes hooks test pre_tool_call
hermes hooks test pre_tool_call --for-tool terminal
hermes hooks test subagent_stop --payload-file ./payload.json| Flag | Description |
|---|---|
event (positional) |
Hook event name, e.g. pre_tool_call, pre_llm_call, subagent_stop. |
--for-tool FOR_TOOL |
Only fire hooks whose matcher matches this tool name (used for pre_tool_call / post_tool_call). |
--payload-file PAYLOAD_FILE |
Path to a JSON file merged into the synthetic payload before execution. |
revoke (or remove, rm) — Remove a command’s allowlist entries
hermes hooks revoke "~/.hermes/hooks/notify.sh"
hermes hooks rm "~/.hermes/hooks/notify.sh"Removes allowlist entries for the exact command string declared in config.yaml. The change takes effect on the next Hermes restart.
doctor — Check every configured hook
hermes hooks doctorValidates each hook for: executable bit, allowlist state, mtime drift, JSON validity, and synthetic run timing.
Common Scenarios
Review all hooks after editing config
hermes config edit
hermes hooks listTest a hook before approving it
hermes hooks test pre_tool_call --for-tool terminalRevoke consent for a hook
hermes hooks revoke "~/.hermes/hooks/backup.sh"Diagnose hook problems
hermes hooks doctorTips
- Hooks are defined in
~/.hermes/config.yaml; consent is tracked separately in~/.hermes/shell-hooks-allowlist.json. - Revoking consent does not delete the hook definition — it only resets approval, and the change applies after restarting Hermes.
- Use
hermes hooks testwith--payload-fileto simulate realistic payloads without running a full session. hermes hooks doctoris the fastest way to find permission, syntax, or timing issues in configured hooks.- Always review hook scripts before granting consent; they run with the same permissions as the Hermes process.