Claude Code Hooks Builder

"hooks": {}

This is the "hooks" key only — paste it inside the top-level { } of your settings file (add a comma if other keys follow). Already have a "hooks" key? Merge the event arrays. Building the rest of the file — permissions, env, model? That's the settings.json Builder's job.

Reference verified against Claude Code v2.1.205 — July 8, 2026. Hooks change between releases; if something below disagrees with your install, trust claude --version and the official reference, then tell us.

Claude Code hooks, explained

A hook is a standing order: a shell command Claude Code runs automatically, every time, at a fixed point in its lifecycle. Before a tool call. After a file edit. When a session starts. When Claude thinks it's finished. You configure hooks once under the "hooks" key in a settings file, and from then on the behavior is deterministic — unlike an instruction in CLAUDE.md, which Claude should follow, a hook always runs.

That determinism is the whole point. "Please run prettier after editing" works until it doesn't; a PostToolUse hook on Edit|Write works every time, forever, without spending a single token reminding anyone. Hooks are how you turn a habit into infrastructure.

One warning before anything else: hooks run with your full user permissions, without asking. A hook is code you have agreed to execute unattended. Read every command before you register it — especially ones you copied from the internet, including this page.

Quick start

The smallest useful hook — log every shell command Claude runs, so you always have an audit trail. In ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/bash-log.txt"
          }
        ]
      }
    ]
  }
}

Reading it inside-out: when the PreToolUse event fires and the tool name matches Bash, run this command. The hook receives the event as JSON on stdin — here jq plucks out the command text and appends it to a log. That's the entire model. Everything else on this page is detail on the three questions every hook answers: when (the event), on what (the matcher), and do what (the hook entry).

Every hook event

Claude Code fires hooks at thirty points in its lifecycle. You will use five of them constantly and the rest rarely — but "rarely" is exactly when you'll want this table. The Blocks? column says whether the hook can veto the action by exiting with code 2 (details under exit codes).

The core five

Tool and permission events

Session lifecycle

Agents, tasks, and teammates

Environment and config

The configuration shape

Every hook config has the same three levels of nesting, and most first-attempt failures are a missing level. Memorize the skeleton:

"hooks": {                          // 1. the event map
  "PreToolUse": [                   // 2. a list of matcher groups per event
    {
      "matcher": "Bash",            //    which occurrences this group cares about
      "hooks": [                    // 3. the hooks that run when it matches
        { "type": "command", "command": "./check.sh", "timeout": 30 }
      ]
    }
  ]
}

Notes that save debugging time:

• matcher is optional. Omit it (or use "*" or "") and the group fires on every occurrence of the event. Events that don't support matchers (Stop, UserPromptSubmit, CwdChanged…) simply ignore it.
• One event can have many matcher groups, and one group can have many hooks. All matching hooks run; identical commands are deduplicated.
• timeout is per-hook, in seconds. Default 600 for commands (30 for UserPromptSubmit, 10 for MessageDisplay).
• "type": "command" is what this builder emits and what you almost always want. Four other types exist: prompt (a one-shot LLM yes/no check), agent (a subagent verification loop), http (POST the event to a URL), and mcp_tool (call a tool on a connected MCP server). Reach for them when a shell one-liner can't express the judgment call.
• A hook entry can also carry an if field using permission-rule syntax — "if": "Bash(git *)" runs the hook only for git commands, cheaper than parsing stdin yourself. It's evaluated on tool events only (PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, PermissionDenied).

Matchers

The matcher string is interpreted in one of three ways:

• Match everything: "*", "", or omitted.
• Exact name(s): plain names, separated by | or commas — Bash, Edit|Write, Edit,Write.
• Regex: anything with regex characters is evaluated as an unanchored JavaScript regex — mcp__.* matches every MCP tool, mcp__github__.* everything from one server.

What the matcher compares against depends on the event:

What your hook receives

Every hook gets one JSON object on stdin. The common fields:

{
  "session_id": "…",
  "prompt_id": "…",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/current/working/directory",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse"
}

Each event adds its own fields — the ones you'll actually parse:

jq is the standard way in: jq -r '.tool_input.file_path' and you're off. For anything longer than a one-liner, write a script that reads stdin and point the hook at the script.

What your hook says back: exit codes and JSON

Hooks talk back through their exit code, and optionally through JSON on stdout.

• Exit 0 — success. stdout is parsed for JSON output (below); for SessionStart and UserPromptSubmit, plain stdout becomes context Claude sees.
• Exit 2 — block, where the event supports it. stderr becomes the explanation: for PreToolUse the tool call is cancelled and Claude reads your stderr; for Stop Claude isn't allowed to finish and your stderr becomes its next instruction; for UserPromptSubmit the prompt is swallowed. On non-blocking events, exit 2 just shows stderr.
• Anything else — non-blocking error; stderr appears in the transcript, execution continues.

For decisions richer than block/allow, print JSON on stdout with exit 0:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Writes to /etc are off-limits in this repo."
  }
}

The fields worth knowing: permissionDecision (allow / deny / ask / defer) pre-answers the permission check on PreToolUse; updatedInput rewrites the tool's arguments before it runs; additionalContext injects text into Claude's context; continue: false with a stopReason halts processing outright; and suppressOutput: true keeps your hook's stdout out of the transcript. A top-level "decision": "block" with a "reason" is the JSON equivalent of exit 2 on Stop and PostToolUse.

Where hooks live

Plugins can ship hooks in hooks/hooks.json, and skills and agents can carry hooks in their frontmatter that apply only while they're active. All sources merge; to turn everything off temporarily, set "disableAllHooks": true. To build the settings file these fragments paste into — permissions, env, model, the works — use the settings.json Builder.

Worked examples

Each of these is a complete "hooks" fragment — the same output the builder produces. Load puts it in the builder above so you can tweak before copying.

Auto-format after every edit

The classic. Prettier runs on every file Claude edits or writes, the moment it happens. Swap in black, gofmt, or rustfmt to taste.

"hooks": {
  "PostToolUse": [
    {
      "matcher": "Edit|Write",
      "hooks": [
        {
          "type": "command",
          "command": "jq -r '.tool_input.file_path // empty' | xargs -r npx prettier --write --ignore-unknown"
        }
      ]
    }
  ]
}

Load into builder

Block dangerous rm commands

A PreToolUse guard on Bash: if the command smells like a recursive delete of home or root, exit 2 — the call is blocked and Claude is told why. Deterministic, unlike hoping the model declines.

"hooks": {
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        {
          "type": "command",
          "command": "jq -r '.tool_input.command' | grep -qE 'rm .*-[a-z]*r[a-z]*f|rm .*-[a-z]*f[a-z]*r' && { echo 'Blocked: recursive force delete. Ask the human.' >&2; exit 2; } || exit 0"
        }
      ]
    }
  ]
}

Load into builder

Log every Bash command

An audit trail of everything Claude runs, one line per command, timestamped. Costs nothing, and the one day you need it you'll really need it.

"hooks": {
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        {
          "type": "command",
          "command": "jq -r '\"[\\(now | todate)] \\(.tool_input.command)\"' >> ~/.claude/bash-log.txt"
        }
      ]
    }
  ]
}

Load into builder

Desktop notification when Claude needs you

You started a long task and switched windows. This macOS example pings you the moment Claude is waiting on a permission prompt; on Linux, swap in notify-send.

"hooks": {
  "Notification": [
    {
      "matcher": "permission_prompt",
      "hooks": [
        {
          "type": "command",
          "command": "osascript -e 'display notification \"Claude Code is waiting on a permission prompt\" with title \"Claude Code\"'"
        }
      ]
    }
  ]
}

Load into builder

Play a sound when Claude finishes

"hooks": {
  "Stop": [
    {
      "hooks": [
        {
          "type": "command",
          "command": "afplay /System/Library/Sounds/Glass.aiff"
        }
      ]
    }
  ]
}

Load into builder

Inject git context at session start

On SessionStart, whatever the hook prints becomes context Claude begins with — so every session opens already knowing your branch and dirty files.

"hooks": {
  "SessionStart": [
    {
      "matcher": "startup",
      "hooks": [
        {
          "type": "command",
          "command": "echo \"Branch: $(git branch --show-current 2>/dev/null). Uncommitted: $(git status --porcelain 2>/dev/null | wc -l | tr -d ' ') files.\""
        }
      ]
    }
  ]
}

Load into builder

FAQ

My hook isn't firing. What do I check first?

In order: (1) valid JSON — one trailing comma kills the whole file silently; (2) the nesting — event → matcher group → hooks array, all three levels; (3) the matcher — bash doesn't match Bash, matchers are case-sensitive; (4) run /hooks inside Claude Code to see what's actually registered. Settings edits are normally picked up live, but a restart forces a reload.

Hooks vs. CLAUDE.md instructions — when do I use which?

Instructions are requests; hooks are law. Use CLAUDE.md for judgment calls ("prefer small commits"), hooks for anything that must happen every time (formatting, logging, blocking a path). If you've written the same reminder twice, it wants to be a hook.

Can a Stop hook loop forever?

It can try — a Stop hook that always exits 2 sends Claude back to work indefinitely. Claude Code caps consecutive blocks and sets stop_hook_active: true in your hook's stdin once a block streak is running; well-behaved Stop hooks check it and exit 0.

Do hooks work inside subagents?

Yes — tool events fire in subagents too, and the stdin JSON carries agent_id and agent_type so you can tell. SubagentStart and SubagentStop let you hook the subagent lifecycle itself, with the agent type as the matcher.

Is any of this a security risk?

The hooks mechanism is a security feature — it's how you enforce guardrails. The commands are the risk: they run unattended with your permissions. Treat a hook entry like a cron job — read it, understand it, and be suspicious of anything you didn't write, including snippets from this page.