Cursor Hooks Pack: 8 Ready hooks.json Hooks + Installer + Validator

Eight ready Cursor hooks (.cursor/hooks.json) that stop the agent from doing damage, keep secrets out of the model, and keep it working until the tests pass, plus hookcheck, a checker and simulator that tells you why a hook isn't running.

Python 3.9+, standard library only. No accounts, no network. Written against the Cursor hooks reference as of Nov 2026.

All rules live in one file, .cursor/hooks/policy.json: add your MCP servers to mcp.allow_servers, set stop.test_command (for example npm test or pytest -q), and add or remove patterns. The installer never overwrites your edited policy.json.

python3 tools/install.py /path/to/your/project --dry-run     # see what it will add
python3 tools/install.py /path/to/your/project               # all hooks, project level (.cursor/hooks.json)
python3 tools/install.py /path/to/your/project --only guard_shell,guard_read,scan_prompt
python3 tools/install.py --user                              # for every project (~/.cursor/hooks.json)
python3 tools/install.py /path/to/your/project --uninstall   # removes only what this pack added

The installer merges into an existing hooks.json (your own hooks stay, nothing is added twice), puts guards before observers, and saves hooks.json.bak-<time> first. Cursor reloads hooks.json on save; open the Hooks tab in Customize (or the Hooks output channel) to see them. Commit .cursor/hooks.json and .cursor/hooks/ to share them with your team; cloud agents run project command hooks too (except sessionStart and beforeMCPExecution, which Cursor does not run there).

python3 tools/hookcheck.py check                         # .cursor/hooks.json in this project
python3 tools/hookcheck.py check --user                  # also ~/.cursor/hooks.json
python3 tools/hookcheck.py simulate beforeShellExecution --command "git push --force"
python3 tools/hookcheck.py simulate beforeReadFile --file .env
python3 tools/hookcheck.py simulate stop --status completed
python3 tools/hookcheck.py simulate beforeMCPExecution --input samples/beforeMCPExecution.json
python3 tools/hookcheck.py events                        # every event, its matcher value and output fields

check catches: invalid JSON (trailing commas, comments), missing "version": 1, unknown or Claude Code event names (PreToolUse -> preToolUse), misspelled options, script paths that don't resolve from where the hook runs (project hooks run from the project root, so ./hooks/x.sh must be .cursor/hooks/x.sh; user hooks run from ~/.cursor), scripts that aren't executable or have no #! line or Windows line endings, interpreters or jq that aren't installed, invalid matcher regexes, matchers that can never match (afterFileEdit is matched against Write, so "matcher": "Edit" never runs), timeout given in milliseconds, loop_limit on the wrong event, and security hooks without failClosed.

simulate runs the hooks for one event exactly as Cursor would (same working directory, JSON on stdin, CURSOR_PROJECT_DIR, matcher, timeout) and checks the output: one JSON object on stdout, valid permission values for that event, exit code 2 = deny, crashes fail open unless failClosed. It prints the merged decision (deny beats ask beats allow). samples/ has a realistic input for every event.

./tools/demo.sh installs the pack into a throwaway project, checks it and simulates four events (see the preview image).

./run_tests.sh (18 tests, Python 3.13 and 3.10): 11 deny, 11 ask and 10 allow shell cases (including look-alikes such as rm -rf /tmp/build and curl ... | jq), MCP allow-list and write-tool rules, protected files and secret content, prompt secret detection, audit redaction, the stop loop (fails -> follow-up, stops at the limit), the session briefing in a real git repo, install/merge/uninstall that keeps your own hooks and policy, and the checker/simulator on broken configs.

• Hooks are a safety net, not a sandbox: a determined agent can still do damage through a path no rule covers. Keep Cursor's own approval settings on for anything that matters.
• Pattern rules can miss obfuscated commands (variables, base64, aliases) and can flag harmless ones; edit policy.json.
• The scripts are tested on macOS/Linux/WSL. On Windows, Cursor runs hooks through PowerShell: install with --python py (or python) and run hookcheck check there.
• simulate runs your hooks locally with sample events; real Cursor input can carry more fields. Event names and fields follow the Cursor docs as of Nov 2026; Cursor may change them.