Cmd. /hooks
Inspect configured Claude Code hooks and diagnose missing runs by separating event matching, handler failures, and unexpected results.
Written and reviewed by Eric Han · Co-founder & CTO, reopt
Key takeaways
- A configured hook is not proof that its handler ran.
- Separate event matching from handler errors before changing the configuration.
- Use the hook implementation guide for configuration and return-value examples.
Purpose
Inspect hook configuration and events.
/hooksAvailability
| Field | Value |
|---|---|
| Input surface | Running CLI prompt |
| Kind | Built-in |
| Status | Current reference |
| Aliases | — |
| Documented minimum | Not specified |
| Reviewed against | 2026-10-23 · Claude Code 2.1.308 |
The installed command menu and account or organization settings determine availability.
Examples
/hooksDiagnose a formatter that did not run
Consider a formatter configured for PostToolUse with an Edit|Write matcher. This is a diagnostic exercise, not a measured production incident.
| Observation | Evidence to collect | Next step |
|---|---|---|
Configuration is missing from /hooks | Project and settings scope | Check that you opened the intended project |
| Configuration appears, but no run is recorded | Actual tool name in the session | Distinguish a Bash file change from an Edit or Write call |
| Handler starts and fails | Exit code, stderr, working directory | Reproduce the handler failure with sanitized input |
| Handler succeeds without changing the file | Target file and expected formatting difference | Check whether it processed another file or had nothing to change |
Record the event, matcher, and command shown by /hooks. Then request one change to a disposable file and compare the actual tool call with those settings. Opening the menu alone is not an execution test.
Keep the CLI version, project, expected result, and actual result with the reproduction. Avoid broadening the matcher until the mismatch is understood. For configuration changes, continue to the hook implementation guide.
Effects and persistence
Shows configured hooks and their triggers. Editing a hook changes what runs when its event occurs.
From v2.1.299, UserPromptSubmit precedes skill/command expansion; a skill’s own hook begins with the following prompt. v2.1.300 validates updatedInput; v2.1.302 limits concurrent prompt/agent hooks of one event to 12.
Cautions
Inspect event, command, and scope together. A hook can execute whenever its configured event occurs. From v2.1.286, /hooks opens on one list of configured hooks grouped by event, so viewing a hook takes one Enter instead of three. From v2.1.292, <system-reminder> tags written in a hook's output are escaped before they reach Claude.