CLI Coming Soon
    Back to catalog

    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:

    LocationScopeShareable
    ~/.claude/settings.jsonAll your projectsNo, local to your machine
    .claude/settings.jsonSingle projectYes, can be committed to the repo
    .claude/settings.local.jsonSingle projectNo, gitignored when Claude Code saves a setting to it
    Managed policy settingsOrganization-wideYes, admin-controlled
    Plugin hooks/hooks.jsonWhen plugin is enabledYes, bundled with the plugin
    Skill frontmatterThe rest of the session once the skill is invoked. See Hooks in skills and agentsYes, defined in the skill file
    Subagent frontmatterWhile that subagent is runningYes, 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.

    EventWhen it firesMatcher filtersHandler types
    SessionStartWhen a session begins or resumeshow the session startedcommand, mcp_tool
    SetupWhen you start Claude Code with --init-only, or with --init or --maintenance in -p mode. For one-time preparation in CI or scriptswhich CLI flag triggered setupcommand
    UserPromptSubmitWhen a prompt is submitted, before Claude processes it. Also fires on turns Claude Code starts on its ownno matcher supportcommand, http, mcp_tool, prompt, agent
    UserPromptExpansionWhen a user-typed command expands into a prompt, before it reaches Claude. Can block the expansioncommand namecommand, http, mcp_tool, prompt, agent
    PreToolUseBefore a tool call executes. Can block ittool namecommand, http, mcp_tool, prompt, agent
    PermissionRequestWhen a tool call needs a permission decisiontool namecommand, http, mcp_tool, prompt
    PermissionDeniedWhen 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 verdicttool namecommand, http, mcp_tool, prompt, agent
    PostToolUseAfter a tool call succeedstool namecommand, http, mcp_tool, prompt, agent
    PostToolUseFailureAfter a tool call failstool namecommand, http, mcp_tool, prompt, agent
    PostToolBatchAfter a full batch of parallel tool calls resolves, before the next model callno matcher supportcommand, http, mcp_tool, prompt, agent
    NotificationWhen Claude Code sends a notificationnotification typecommand, http, mcp_tool
    MessageDisplayWhile assistant message text is displayedno matcher supportcommand, http, mcp_tool
    SubagentStartWhen a subagent is spawnedagent typecommand, http, mcp_tool
    SubagentStopWhen a subagent finishesagent typecommand, http, mcp_tool, prompt, agent
    TaskCreatedWhen a task is being created via TaskCreateno matcher supportcommand, http, mcp_tool, prompt, agent
    TaskCompletedWhen a task is being marked as completedno matcher supportcommand, http, mcp_tool, prompt, agent
    StopWhen Claude finishes respondingno matcher supportcommand, http, mcp_tool, prompt, agent
    StopFailureWhen the turn ends due to an API errorerror typecommand, http, mcp_tool
    TeammateIdleWhen an agent team teammate is about to go idleno matcher supportcommand, http, mcp_tool, prompt, agent
    InstructionsLoadedWhen a CLAUDE.md or .claude/rules/*.md file is loaded into context. Fires at session start and when files are lazily loaded during a sessionload reasoncommand, http, mcp_tool
    ConfigChangeWhen a configuration file changes during a sessionconfiguration sourcecommand, http, mcp_tool
    CwdChangedWhen the working directory changes, for example when Claude executes a cd command. Useful for reactive environment management with tools like direnvno matcher supportcommand, http, mcp_tool
    DirectoryAddedWhen a working directory is added mid-session via /add-dir or the SDK register_repo_root control requesthow the directory was addedcommand, http, mcp_tool
    FileChangedWhen a watched file changes on disk. The matcher field specifies which filenames to watchliteral filenames to watch (see FileChanged)command, http, mcp_tool
    WorktreeCreateWhen a worktree is being created via --worktree, isolation: "worktree", or for a background session. Replaces default git behaviorno matcher supportcommand, http, mcp_tool
    WorktreeRemoveWhen a worktree that a WorktreeCreate hook created is being removedno matcher supportcommand, http, mcp_tool
    PreCompactBefore context compactionwhat triggered compactioncommand, http, mcp_tool
    PostCompactAfter context compaction completeswhat triggered compactioncommand, http, mcp_tool
    PreModelSwitchBefore Claude Code applies a model switch that you or a client requested. Can block the switchcanonical name of the model the session switches to, as described under PreModelSwitchcommand, http, mcp_tool
    PostModelSwitchAfter the session's model changes, including changes Claude Code makes on its own, such as restoring the model when you resume a sessioncanonical name of the model the session switches to, as described under PreModelSwitchcommand, http, mcp_tool
    ElicitationWhen an MCP server requests user input during a tool callMCP server namecommand, http, mcp_tool
    ElicitationResultAfter a user responds to an MCP elicitation, before the response is sent back to the serverMCP server namecommand, http, mcp_tool
    SessionEndWhen a session terminateswhy the session endedcommand, 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

    1. 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.
    2. 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.
    3. 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.
    4. 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, && in if, an MCP tool hook on SessionStart, and agent hooks being experimental.
    5. 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, HTTP headers and allowedEnvVars, MCP input, and prompt model. 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

    Sources

    All read on 2026-11-12. The hash is the sha256 of the page's Markdown export (the page URL with .md added).