Claude Code hooks builder
Published · Last updated · Docs checked 2026-11-12
A Claude Code hook goes in settings.json under hooks, in three levels: an event such as PreToolUse, a matcher group such as Bash, and a handler such as a shell command. Pick an event and a matcher, enter a command, and copy the block below.
Build a hook
Runs in your browser. Nothing you type is uploaded or stored. No AI model reads it.
Fires: "Before a tool call executes. Can block it" (PreToolUse in the docs)
Empty matches every tool name. Values in the docs: Bash, Edit|Write, mcp__.*. Matcher patterns
PreToolUse takes 5 of the 5 types (which events take which types).
Your script gets the event's JSON on stdin.
Optional fields
- Enter the command. The docs list it as required for command hooks.
The hooks block shows here once the required field is filled in.
Claude Code hooks examples from the docs
Each block below is copied as written from Anthropic's docs, with a link to its section. The builder prints each one back exactly when you load it. Where the docs name a settings file, it is shown.
Desktop notification when Claude needs input (macOS)
Event Notification. From Get notified when Claude needs input in the hooks guide, which says to add it to ~/.claude/settings.json.
{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
}
]
}
]
}
}Desktop notification when Claude needs input (Linux)
Event Notification. From Get notified when Claude needs input in the hooks guide, which says to add it to ~/.claude/settings.json.
{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
}
]
}
]
}
}Block edits to protected files
Event PreToolUse. From Block edits to protected files in the hooks guide, which says to add it to .claude/settings.json. The command calls a script the same section gives you to save first.
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
}
]
}
]
}
}Re-inject context after compaction
Event SessionStart. From Re-inject context after compaction in the hooks guide, which says to add it to .claude/settings.json.
{
"hooks": {
"SessionStart": [
{
"matcher": "compact",
"hooks": [
{
"type": "command",
"command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
}
]
}
]
}
}Log configuration changes
Event ConfigChange. From Audit configuration changes in the hooks guide, which says to add it to ~/.claude/settings.json.
{
"hooks": {
"ConfigChange": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "jq -c '{timestamp: now | todate, source: .source, file: .file_path}' >> ~/claude-config-audit.log"
}
]
}
]
}
}Reload the environment when .envrc or .env changes
Event FileChanged. From Reload environment when directory or files change in the hooks guide.
{
"hooks": {
"FileChanged": [
{
"matcher": ".envrc|.env",
"hooks": [
{
"type": "command",
"command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
}
]
}
]
}
}Auto-approve the ExitPlanMode prompt
Event PermissionRequest. From Auto-approve specific permission prompts in the hooks guide, which says to add it to ~/.claude/settings.json.
{
"hooks": {
"PermissionRequest": [
{
"matcher": "ExitPlanMode",
"hooks": [
{
"type": "command",
"command": "jq -c '{hookSpecificOutput: {hookEventName: \"PermissionRequest\", decision: {behavior: \"allow\", updatedInput: .tool_input}}}'"
}
]
}
]
}
}Run a check only on git commands (the if field)
Event PreToolUse. From Filter by tool name and arguments with the if field in the hooks guide. check-git-policy.sh stands for your own script.
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"if": "Bash(git *)",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh"
}
]
}
]
}
}Run a lint script after Edit or Write
Event PostToolUse. From Matcher patterns in the hooks reference. /path/to/lint-check.sh stands for your own script.
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "/path/to/lint-check.sh"
}
]
}
]
}
}Ask a model whether all tasks are done before stopping
Event Stop. From Prompt-based hooks in the hooks guide.
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "prompt",
"prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
}
]
}
]
}
}Have an agent check tests pass before stopping
Event Stop. From Agent-based hooks in the hooks guide.
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "agent",
"prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
"timeout": 120
}
]
}
]
}
}The guide also has an auto-format example that pipes edited files to Prettier. It is not a preset here because its command runs npx prettier with no pinned version. Pin the version you use if you copy it.
Where the hooks block goes
From Hook locations in the hooks reference. The three settings files take the block as the builder prints it:
| Location | Scope | Shareable |
|---|---|---|
~/.claude/settings.json | All your projects | No, local to your machine |
.claude/settings.json | Single project | Yes, can be committed to the repo |
.claude/settings.local.json | Single project | No, gitignored when Claude Code saves a setting to it |
| Managed policy settings | Organization-wide | Yes, admin-controlled |
Plugin hooks/hooks.json | When plugin is enabled | Yes, bundled with the plugin |
| Skill frontmatter | The rest of the session once the skill is invoked. See Hooks in skills and agents | Yes, defined in the skill file |
| Subagent frontmatter | While that subagent is running | Yes, defined in the subagent file |
Hooks from different files add up rather than replace each other: "user, project, and local settings add their own hooks without removing managed ones" (Hook locations). The docs also say "If you edit settings files directly while Claude Code is running, the file watcher normally picks up hook changes automatically" (Configure hook location). Type /hooks to see every hook Claude Code loaded and where it came from.
Every hook event and what it does
The 33 events in the hook lifecycle table as of 2026-11-12. "When it fires" and "Matcher filters" are quoted from the docs.
| Event | When it fires | Matcher filters | Handler types |
|---|---|---|---|
| SessionStart | When a session begins or resumes | how the session started | command, mcp_tool |
| Setup | When you start Claude Code with --init-only, or with --init or --maintenance in -p mode. For one-time preparation in CI or scripts | which CLI flag triggered setup | command |
| UserPromptSubmit | When a prompt is submitted, before Claude processes it. Also fires on turns Claude Code starts on its own | no matcher support | command, http, mcp_tool, prompt, agent |
| UserPromptExpansion | When a user-typed command expands into a prompt, before it reaches Claude. Can block the expansion | command name | command, http, mcp_tool, prompt, agent |
| PreToolUse | Before a tool call executes. Can block it | tool name | command, http, mcp_tool, prompt, agent |
| PermissionRequest | When a tool call needs a permission decision | tool name | command, http, mcp_tool, prompt |
| PermissionDenied | When auto mode denies a tool call, including denials without a classifier verdict. Use JSON hookSpecificOutput.retry: true to tell the model it may retry the denied tool call. Claude Code ignores retry when the classifier produced no verdict | tool name | command, http, mcp_tool, prompt, agent |
| PostToolUse | After a tool call succeeds | tool name | command, http, mcp_tool, prompt, agent |
| PostToolUseFailure | After a tool call fails | tool name | command, http, mcp_tool, prompt, agent |
| PostToolBatch | After a full batch of parallel tool calls resolves, before the next model call | no matcher support | command, http, mcp_tool, prompt, agent |
| Notification | When Claude Code sends a notification | notification type | command, http, mcp_tool |
| MessageDisplay | While assistant message text is displayed | no matcher support | command, http, mcp_tool |
| SubagentStart | When a subagent is spawned | agent type | command, http, mcp_tool |
| SubagentStop | When a subagent finishes | agent type | command, http, mcp_tool, prompt, agent |
| TaskCreated | When a task is being created via TaskCreate | no matcher support | command, http, mcp_tool, prompt, agent |
| TaskCompleted | When a task is being marked as completed | no matcher support | command, http, mcp_tool, prompt, agent |
| Stop | When Claude finishes responding | no matcher support | command, http, mcp_tool, prompt, agent |
| StopFailure | When the turn ends due to an API error | error type | command, http, mcp_tool |
| TeammateIdle | When an agent team teammate is about to go idle | no matcher support | command, http, mcp_tool, prompt, agent |
| InstructionsLoaded | When a CLAUDE.md or .claude/rules/*.md file is loaded into context. Fires at session start and when files are lazily loaded during a session | load reason | command, http, mcp_tool |
| ConfigChange | When a configuration file changes during a session | configuration source | command, http, mcp_tool |
| CwdChanged | When the working directory changes, for example when Claude executes a cd command. Useful for reactive environment management with tools like direnv | no matcher support | command, http, mcp_tool |
| DirectoryAdded | When a working directory is added mid-session via /add-dir or the SDK register_repo_root control request | how the directory was added | command, http, mcp_tool |
| FileChanged | When a watched file changes on disk. The matcher field specifies which filenames to watch | literal filenames to watch (see FileChanged) | command, http, mcp_tool |
| WorktreeCreate | When a worktree is being created via --worktree, isolation: "worktree", or for a background session. Replaces default git behavior | no matcher support | command, http, mcp_tool |
| WorktreeRemove | When a worktree that a WorktreeCreate hook created is being removed | no matcher support | command, http, mcp_tool |
| PreCompact | Before context compaction | what triggered compaction | command, http, mcp_tool |
| PostCompact | After context compaction completes | what triggered compaction | command, http, mcp_tool |
| PreModelSwitch | Before Claude Code applies a model switch that you or a client requested. Can block the switch | canonical name of the model the session switches to, as described under PreModelSwitch | command, http, mcp_tool |
| PostModelSwitch | After the session's model changes, including changes Claude Code makes on its own, such as restoring the model when you resume a session | canonical name of the model the session switches to, as described under PreModelSwitch | command, http, mcp_tool |
| Elicitation | When an MCP server requests user input during a tool call | MCP server name | command, http, mcp_tool |
| ElicitationResult | After a user responds to an MCP elicitation, before the response is sent back to the server | MCP server name | command, http, mcp_tool |
| SessionEnd | When a session terminates | why the session ended | command, http, mcp_tool |
The five handler types
From Hook handler fields. Required fields first; the builder fills in the required one and offers if, timeout, statusMessage and async.
command: run a shell command. Fields:command(required),args,async,asyncRewake,shell,onFailure.http: POST the event to a URL. Fields:url(required),headers,allowedEnvVars,onFailure.mcp_tool: call a tool on an MCP server. Fields:server(required),tool(required),input.prompt: ask a Claude model for a yes or no. Fields:prompt(required),model.agent: a subagent checks, then decides. Fields:prompt(required),model.
Every type also takes the common fields: type, if, timeout, statusMessage, once. The docs say once is "Only honored for hooks declared in skill frontmatter; ignored in settings files and agent frontmatter", so the builder leaves it out.
How it works
- A script in this site's repo reads the Markdown of the hooks reference and the hooks guide and writes a data file: the event list, which events take a matcher and what it filters on, which handler types each event accepts, the hook locations table and the example blocks. Nothing on this page is typed from memory.
- The event menu holds those 33 events. The matcher box only appears for events the docs give a matcher, and its suggestions are the docs' example values. The handler menu lists only the types the docs say that event runs.
- The block is built as event, then one matcher group, then one handler, the three levels in Configuration, and printed as JSON with two-space indents.
- A few notes quote the docs when an input will not do what you expect: an MCP matcher without
.*, a tool name in the wrong case,&&inif, an MCP tool hook on SessionStart, and agent hooks being experimental. - The page records the sha256 of each docs page under Sources, so you can tell if a page changed after 2026-11-12.
What it does not cover
- Exec form (
args),shell,onFailure,asyncRewake, HTTPheadersandallowedEnvVars, MCPinput, and promptmodel. Add them by hand from the handler fields tables. - More than one matcher group or handler per event. Copy the inner object to add another.
- The script your command runs. What it reads on stdin and what exit code 2 does differ by event; see Hook input and output.
- The rest of your settings.json. Check your whole file with the settings.json validator.
FAQ
What are some Claude Code hooks examples?
Anthropic's hooks guide shows a desktop notification when Claude needs input, a script that blocks edits to .env and .git/, a SessionStart hook that re-adds context after compaction, a config change log, a direnv reload, auto-approval of the plan prompt, and prompt and agent hooks that check work before Claude stops. All 11 single-hook examples are listed above, linked to their section, and load into the builder in one click.
How do I add a hook in Claude Code?
Open a settings file, such as ~/.claude/settings.json for every project or .claude/settings.json for one project, and add a hooks block. If the file already has a hooks key, put the new event next to the existing ones. Then type /hooks in Claude Code: the docs say "Your new hook appears in the list" under its event (Set up your first hook). The docs also say you can ask Claude to write the hook for you.
Which settings file should a hook go in?
~/.claude/settings.json runs it in all your projects. .claude/settings.json runs it in one project and can be committed for your team. .claude/settings.local.json runs it in one project for you only (Hook locations). Plugins, skills and subagents can carry hooks too: the subagent builder puts a hooks block in a subagent file.
Which hook events take a matcher?
All but 10. These have no matcher support and fire every time: CwdChanged, UserPromptSubmit, PostToolBatch, Stop, TeammateIdle, TaskCreated, TaskCompleted, WorktreeCreate, WorktreeRemove, MessageDisplay. The docs say "If you add a matcher field to an event without matcher support, it is silently ignored" (Matcher patterns). The builder hides the field for those events.
What is the difference between matcher and if?
matcher sits on the group and filters by one field, the tool name for tool events. if sits on one handler and takes a permission rule such as Bash(git *), so it can look at the command too. if only works on PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, PermissionDenied; on other events "a hook with if set never runs" (Common fields).
Why is my hook not firing?
Run /hooks and check the hook is listed under the right event. Matchers are case-sensitive, so bash does not match the Bash tool. PreToolUse fires before a tool runs and PostToolUse after (Hook not firing). If a script never runs, make it executable with chmod +x.
Is what I type uploaded anywhere?
No. The builder is JavaScript running in your browser. There is no backend, no API key and no model call. Keep tokens out of the command itself: the docs' HTTP example reads one from an environment variable named in allowedEnvVars.
Related
- Claude Code settings.json validator: check your whole file
- CLAUDE.md linter: check your file against Claude Code best practices
- SKILL.md validator: check a Claude skill against the spec
- Claude Code with Claude Fable 5.2: setup and cost
- All free Claude Code tools
- Browse Claude skills, agents and hooks
Sources
All read on 2026-11-12. The hash is the sha256 of the page's Markdown export (the page URL with .md added).
- Hooks reference (Claude Code docs): https://code.claude.com/docs/en/hooks
sha256 ebb8e6a8edbdf997f9637389d31cd0d8c0f23eb4e7053f6c6bbad490cea8dea3 - Automate actions with hooks (hooks guide) (Claude Code docs): https://code.claude.com/docs/en/hooks-guide
sha256 4407b178d0c33520be74222ecff175c2cbc2a08442c1f9418406f1269effcaf9 - Claude Code settings (Claude Code docs): https://code.claude.com/docs/en/settings
sha256 e180e905de3bbf69dd932eb37a2ea9af8d7e937ade9cc98fdcd493df85ca18cc - Configure permissions (rule syntax for if) (Claude Code docs): https://code.claude.com/docs/en/permissions
sha256 86be6c5404b154e7dec0dc5aca2d145eb53e01c75d1cb9843fdce3da2f4a37f8