Cursor hooks: hooks.json, beforeShellExecution, afterFileEdit and exit codes

Cursor reads hooks from several places. From highest to lowest priority:

• Enterprise (MDM): /Library/Application Support/Cursor/hooks.json on macOS, /etc/cursor/hooks.json on Linux and WSL, C:\ProgramData\Cursor\hooks.json on Windows.
• Team: set in the web dashboard and synced to members (Enterprise only).
• Project: <project-root>/.cursor/hooks.json
• User: ~/.cursor/hooks.json

Project hooks run from the project root, so use paths like .cursor/hooks/script.sh. User hooks run from ~/.cursor/, so use paths like ./hooks/script.sh.

The top-level version must be a positive integer. Use 1. Each event holds a list of hook entries.

{
  "version": 1,
  "hooks": {
    "afterFileEdit": [{ "command": ".cursor/hooks/format.sh" }]
  }
}

• command (required): script path or command.
• type: "command" (default) or "prompt".
• timeout: execution timeout in seconds.
• matcher: regex that filters when the hook runs. Empty or "*" matches everything.
• failClosed: when true, a crash, timeout, non-zero exit or missing output blocks the action. Default false.
• loop_limit: per-script limit on follow-ups for stop and subagentStop hooks. Default 5, null removes the cap.

• Agent: sessionStart, sessionEnd, preToolUse, postToolUse, postToolUseFailure, subagentStart, subagentStop, beforeShellExecution, afterShellExecution, beforeMCPExecution, afterMCPExecution, beforeReadFile, afterFileEdit, beforeSubmitPrompt, preCompact, stop, afterAgentResponse, afterAgentThought
• Tab: beforeTabFileRead, afterTabFileEdit
• App lifecycle: workspaceOpen

For beforeShellExecution, the matcher is tested against the full command string. For preToolUse, it is tested against the tool type, such as Shell, Read or Write.

Every hook gets JSON on stdin with common fields such as conversation_id, generation_id, model, hook_event_name, cursor_version, workspace_roots, user_email and transcript_path. Each event adds its own fields.

• beforeShellExecution input: command, cwd, sandbox. Output: permission ("allow", "deny" or "ask"), user_message, agent_message.
• afterFileEdit input: file_path and edits (a list of old_string and new_string pairs).
• preToolUse output: permission, user_message, agent_message, updated_input.
• beforeSubmitPrompt output: continue, user_message.
• stop output: followup_message.

• Exit 0: hook succeeded, Cursor uses the JSON output.
• Exit 2: block the action, same as returning permission "deny".
• Any other code: hook failed and the action proceeds (fail open), unless failClosed is true.
• For permission hooks, invalid JSON or output that does not match the schema blocks the action.

{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      { "command": ".cursor/hooks/block-risky.sh", "matcher": "rm -rf|curl|wget" }
    ]
  }
}

#!/bin/bash
cat > /dev/null
echo '{"permission": "deny", "user_message": "Blocked by project hook", "agent_message": "This command is not allowed in this repo. Ask the user to run it."}'
exit 0

chmod +x .cursor/hooks/block-risky.sh

Because the matcher only fires on matching commands, the script can simply deny. Use "ask" instead of "deny" if you want the user to approve.

#!/bin/bash
# Requires jq and prettier
file=$(jq -r '.file_path')
npx prettier --write "$file" > /dev/null 2>&1
exit 0

Wire it to afterFileEdit as shown above and make it executable with chmod +x. Cursor watches hooks config files and reloads them on save. If a hook does not load, check the Hooks output channel for errors, or restart Cursor.