Hooks
Hooks
.cursor/hooks.json
Vendor docs
event
| name | type | required | meaning | concept | |
|---|---|---|---|---|---|
| afterAgentResponse | event | docs ↗ | |||
| afterAgentThought | event | docs ↗ | |||
| afterFileEdit | event | docs ↗ | |||
| afterMCPExecution | event | docs ↗ | |||
| afterShellExecution | event | docs ↗ | |||
| afterTabFileEdit | event | docs ↗ | |||
| beforeMCPExecution | event | docs ↗ | |||
| beforeReadFile | event | docs ↗ | |||
| beforeShellExecution | event | docs ↗ | |||
| beforeSubmitPrompt | event | docs ↗ | |||
| beforeTabFileRead | event | docs ↗ | |||
| postToolUse | event | docs ↗ | |||
| postToolUseFailure | event | docs ↗ | |||
| preCompact | event | docs ↗ | |||
| preToolUse | event | docs ↗ | |||
| sessionEnd | event | docs ↗ | |||
| sessionStart | event | docs ↗ | |||
| stop | event | docs ↗ | |||
| subagentStart | event | docs ↗ | |||
| subagentStop | event | docs ↗ | |||
| workspaceOpen | event | docs ↗ |
config
| name | type | required | meaning | concept | |
|---|---|---|---|---|---|
| command | string | yes |
Script path or command
|
docs ↗ | |
| failClosed | boolean |
When `true`, hook failures (crash, timeout, invalid JSON) block the action instead of allowing it through. Useful for security-critical hooks.
|
docs ↗ | ||
| loop_limit | string |
`5`
|
docs ↗ | ||
| matcher | object |
Filter criteria for when hook runs
|
docs ↗ | ||
| timeout | number |
Execution timeout in seconds
|
docs ↗ | ||
| type | string |
`"command"`
|
docs ↗ | ||
| version | number |
Config schema version
|
docs ↗ |