Claude Code Hooks Starter (Free)

Six small, working Claude Code hooks, one for each event people ask about, plus hooktest, a local tester that runs any hook script (Python, Bash, Node, anything) with a sample event and tells you what Claude Code would do with its output.

Python 3.9+ standard library only. No network. Free to use and change (see LICENSE.txt).

./tools/demo.sh          # runs every hook against a sample event
./run_tests.sh           # 11 test groups

# test YOUR hook, in any language
python3 tools/hooktest.py path/to/your-hook.sh samples/pre_tool_use_bash.json
python3 tools/hooktest.py hooks/block_dangerous.py --event PreToolUse --tool Bash --command "git push -f origin main"
python3 tools/hooktest.py hooks/stop_run_tests.py samples/stop.json --json

hooktest reports the exit code, whether stdout is JSON / plain text / broken JSON, the outcome in plain words (BLOCKS, DENIES, ASKS, adds context, keeps working, non-blocking error) and PROBLEM lines for the usual mistakes: wrong hookEventName, permissionDecision values that don't exist, top-level decision on PreToolUse, decision: "block" without a reason, JSON with a non-zero exit, output over the 10,000-character cap. It exits 1 if there are problems, so you can run it in CI.

As a plugin: enable this folder as a Claude Code plugin; hooks/hooks.json uses ${CLAUDE_PLUGIN_ROOT}.

In one project: copy hooks/ to .claude/hooks/ and merge settings.example.json into .claude/settings.json. Delete the hooks you don't want. Run /hooks in Claude Code to check they're listed.

Settings for the examples (environment variables):

• HOOK_TEST_CMD="npm test" turns on the Stop hook (off when unset). HOOK_TEST_TIMEOUT (seconds, default 300).
• HOOK_FORMAT_CMD="ruff format" forces one formatter; otherwise it picks by file extension and skips formatters that aren't installed.
• HOOK_NOTIFY_OSC=9 for iTerm2 / Windows Terminal / WezTerm (default OSC 777: Ghostty, Warp, urxvt).

• Input arrives as JSON on stdin. Print one JSON object to stdout, or nothing.
• Exit 0 = success, fields apply. Exit 2 = block (PreToolUse, UserPromptSubmit, Stop...) or show stderr to Claude (PostToolUse). Any other exit = non-blocking error: the action goes ahead.
• A PreToolUse hook that prints nothing doesn't approve anything; normal permissions apply.
• Use exec form ("command": "python3", "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/x.py"]) so paths with spaces work.
• A hook that can't start doesn't block unless you set "onFailure": "block" (Claude Code v2.1.295+).

Examples, not a security product. The key patterns catch common formats only. The Stop hook runs your test command with your permissions.