Cursor hooks: every event, the hooks.json format and working examples

Where hooks.json lives

• User: ~/.cursor/hooks.json. Relative commands run from ~/.cursor/.
• Project: .cursor/hooks.json in the repo, committed with the code. Runs only in a trusted workspace; relative commands run from the project root.
• Team: set in the Cursor dashboard on Enterprise plans and synced to members.
• Enterprise: /Library/Application Support/Cursor/hooks.json on macOS, /etc/cursor/hooks.json on Linux, C:\ProgramData\Cursor\hooks.json on Windows.

Every matching hook from every level runs. When their answers differ, deny beats ask and ask beats allow, whichever file they came from. user_message and agent_message are joined together.

The file format

{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      { "command": "./hooks/guard-shell.sh", "matcher": "rm -rf|git push --force", "timeout": 10 }
    ],
    "afterFileEdit": [
      { "command": "./hooks/format.sh" }
    ]
  }
}

• command: a shell command, an absolute path or a path relative to the hooks.json location.
• matcher: a regex. For beforeShellExecution it is tested against the full command; for preToolUse against the tool name (Shell, Read, Write, Grep, Delete, Task or MCP:<tool>). Empty or * matches everything.
• timeout: seconds.
• failClosed: true makes a crash, timeout or empty output block the action. By default a broken hook lets the action through.
• loop_limit: for stop and subagentStop, how many automatic follow-ups are allowed (default 5, null for no limit).
• type: "prompt" runs a model prompt instead of a command (not in cloud agents).

Every agent event

Input and exit codes

Each hook gets one JSON object on stdin. Every event includes conversation_id, generation_id, hook_event_name, cursor_version, workspace_roots, user_email and transcript_path, plus its own fields: command and cwd for beforeShellExecution, file_path and edits for afterFileEdit, status and loop_count for stop.

• Exit 0: success. Cursor reads the JSON you print to stdout.
• Exit 2: block the action, the same as answering permission deny. Claude Code hooks use the same convention.
• Any other exit code: the hook failed and the action goes ahead, unless failClosed is true.
• Permission hooks (preToolUse, beforeShellExecution, beforeMCPExecution, beforeReadFile, subagentStart) block the action if they print invalid JSON, even without failClosed.

Example: block force pushes

#!/bin/bash
# ~/.cursor/hooks/guard-shell.sh (beforeShellExecution)
cmd=$(jq -r '.command')
if echo "$cmd" | grep -qE 'git push (-f|--force)'; then
  echo '{"permission":"deny","user_message":"Force push blocked by a hook.","agent_message":"Force pushes are not allowed. Push normally or ask me."}'
  exit 0
fi
echo '{"permission":"allow"}'

Example: keep going until the tests pass

#!/bin/bash
# .cursor/hooks/tests-pass.sh (stop)
status=$(jq -r '.status')
[ "$status" = "completed" ] || { echo '{}'; exit 0; }
if ! bun test >/dev/null 2>&1; then
  echo '{"followup_message":"The tests are failing. Run bun test, fix the failures, then stop."}'
else
  echo '{}'
fi

Limits

• Cloud agents run command hooks only, skip the user-level ~/.cursor/hooks.json, and don't run sessionStart, sessionEnd, the MCP execution hooks, the Tab hooks or workspaceOpen.
• Project hooks need a trusted workspace.
• On Windows the desktop app runs hook commands through PowerShell.
• preToolUse accepts ask in its schema but doesn't enforce it; use beforeShellExecution or beforeMCPExecution for ask.

Hooks and a shared task board

Hooks see one agent at a time. When several agents run at once, Taskhold puts all of their tasks on one live board: Cursor reports steps and progress through the Taskhold MCP tools, and asks you questions there instead of stopping in the chat. A stop hook covers the runs that end without a word; the ready-made version is on Cursor hook for Taskhold, and connecting Cursor takes one click on the Cursor setup page.