Hooks Generator

What Claude Code hooks actually are

A hook is a shell command that Claude Code runs automatically at a specific point in its lifecycle. You register hooks in settings.json under a `hooks` key, grouped by event name. When that event fires - a tool is about to run, a response just finished, you submitted a prompt - Claude Code executes your command, passes it context as JSON on standard input, and reads its exit code and output. That is the entire model: an event, a matcher, and a command. Hooks are how you turn Claude Code from a thing that suggests actions into a thing that enforces your rules deterministically, because a hook runs every single time, not just when the model remembers to.

The generator above builds a valid hooks block for you. Pick the event you want to react to, pick which tools should trigger it (for tool-lifecycle events), and paste the command you want run. The output is drop-in JSON you merge into settings.json - no guessing at the schema, no malformed matcher strings.

The hook events and when they fire

• PreToolUse - fires before a tool call runs. This is the one that can block. Exit with code 2 and Claude Code cancels the tool call and feeds your message back to the model. Use it for guardrails: block `rm -rf`, block writes outside a directory, require a lint pass before an edit.
• PostToolUse - fires after a tool call completes. Great for reactions: auto-format a file after every Edit, run a type check after a Write, log what was touched.
• UserPromptSubmit - fires when you submit a prompt, before the model sees it. You can inject extra context or validate the prompt.
• Stop - fires when Claude finishes its main response. Good for a done chime, a summary log, or kicking off a follow-up job.
• SubagentStop - fires when a spawned subagent finishes its work.
• SessionStart - fires when a session begins. Use it to print environment info, warm a cache, or load state.
• Notification - fires when Claude Code sends you a notification (for example, when it needs input).
• PreCompact - fires before Claude Code compacts the conversation to reclaim context.

How the matcher works

For the tool-lifecycle events (PreToolUse and PostToolUse), the matcher decides which tools trigger your hook. It is matched against the tool name. An empty matcher or a broad pattern catches every tool; a specific name like Bash catches only shell commands; an alternation like Edit|Write|MultiEdit catches any of several tools. The other events do not run against a specific tool, so they take no matcher - they simply fire on the event itself. The generator hides the matcher field for those events so you never write an ignored one.

What your command receives

Claude Code passes hook context to your command as a JSON object on standard input. That payload includes information about the event - for tool events, the tool name and its input arguments; for prompt events, the submitted text. A common pattern is to pipe stdin through a JSON tool like jq to pull out the field you care about, then decide whether to allow, block, or transform. Your command's exit code controls flow (0 to proceed, 2 to block on PreToolUse), and text you print can be surfaced back to the model or the user.

Project hooks vs personal hooks

Where you put the block matters. Hooks in a project's .claude/settings.json travel with the repo and apply to anyone working in it - use this for team guardrails like formatting and lint gates. Hooks in your personal ~/.claude/settings.json apply to you across every project - use this for your own preferences like a done chime or a personal logging habit. If you want a project hook that stays out of version control, .claude/settings.local.json is the local, gitignored variant. Because hooks execute real shell commands on your machine, only add hooks you understand and trust.

Practical hooks worth stealing

1. Auto-format on save: PostToolUse matching Edit|Write that runs your formatter on the changed file, so Claude's edits are always clean.
2. Block dangerous shell: PreToolUse matching Bash that inspects the command and exits 2 if it contains a destructive pattern.
3. Type-check gate: PostToolUse matching Edit|Write that runs your type checker and reports failures back so Claude fixes them itself.
4. Session banner: SessionStart that prints the current branch, environment, and any active feature flags.
5. Done chime: Stop that plays a sound or sends a desktop notification so you know a long task finished.
6. Prompt logging: UserPromptSubmit that appends your prompts to a local file for later review of what you actually asked.

Debugging a hook that will not fire

If a hook does not seem to run, check the obvious things first: the JSON is valid and lives under the right event key, the matcher actually matches the tool you expect, and the command is executable and on your PATH. Test the command in isolation by feeding it a sample JSON payload on stdin. Remember that a PreToolUse hook that always exits 2 will block everything it matches, which looks like Claude Code refusing to work - loosen the matcher or fix the condition. When in doubt, start with a trivial hook that just echoes and confirm it triggers before wiring in real logic.