Skip to content

Claude Code hooks

By Mari Luukkainen · 5 min read · Last updated

On this page

Claude Code hooks are commands that run automatically at set points in a session, such as before a tool call (PreToolUse), after a file edit (PostToolUse) or when Claude finishes a reply (Stop). You define them in a settings file, and a command hook that exits with code 2 blocks the action. Facts here come from Anthropic's hooks reference, checked 11 November 2026.

Hooks are one of the add-ons covered in what Claude Code is. Use them for what must happen every time; instructions in CLAUDE.md or a skill are guidance Claude may skip. Command hooks run on your machine and cost nothing extra, while prompt and agent hooks call a model and count toward usage, compared on Claude Code pricing.

Ask AI about this pageChatGPTClaudePerplexityGoogle AI ModeGrok

Where do you configure hooks?

LocationApplies to
~/.claude/settings.jsonAll your projects, on this machine only
.claude/settings.jsonOne project, can be committed for the team
.claude/settings.local.jsonOne project, gitignored
Managed policy settingsThe whole organization, set by an admin
A plugin's hooks/hooks.jsonWhile the plugin is enabled
Skill or subagent frontmatterWhile that skill or subagent is active

Hooks from all levels are merged. Run /hooks in a session to see every configured hook and the file it comes from; the view is read-only, so you edit the JSON to change one. To turn all hooks off, set "disableAllHooks": true in a settings file (hooks reference).

Which hook events can you use?

The reference lists over 30 events. These are the ones most setups use:

EventFiresCan block?
SessionStartWhen a session starts or resumesNo
UserPromptSubmitWhen you send a prompt, before Claude reads itYes
PreToolUseBefore a tool call runsYes
PermissionRequestWhen a tool call needs a permission decisionIt can decide
PostToolUseAfter a tool call succeedsNo, the tool already ran, but Claude sees the message
NotificationWhen Claude Code sends a notificationNo
StopWhen Claude finishes respondingYes, Claude keeps working
PreCompactBefore the context is compactedYes, compaction is skipped
SessionEndWhen the session endsNo

Others cover subagent starts and stops, failed tool calls, CLAUDE.md loading, file changes on disk, worktrees and model switches (hooks reference).

How is a hook written?

The config has three levels: the event, a matcher group, and one or more handlers. For tool events the matcher is the tool name. Edit|Write matches either tool, "*" or an empty matcher matches everything, and a matcher with other characters is read as a regular expression, such as mcp__github__.* for every tool of one MCP server.

.claude/settings.json: format files after every edit
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$(jq -r '.tool_input.file_path')\""
          }
        ]
      }
    ]
  }
}

The hook gets the event as JSON on standard input, with fields such as session_id, cwd, permission_mode and hook_event_name, plus the tool input on tool events. Inside the command, CLAUDE_PROJECT_DIR points to the project root, so a script in the repo can be called as "${CLAUDE_PROJECT_DIR}/.claude/hooks/check.sh".

Handlers come in five types: command (a shell command), http (POSTs the JSON to a URL), mcp_tool (calls a tool on an MCP server), prompt (asks a Claude model for a single yes or no style judgement) and agent (an experimental subagent that can use tools to check a condition). Default timeouts are 600 seconds for command, http and mcp_tool hooks, 30 for prompt and 60 for agent (hooks reference).

How does a hook block an action?

Exit codeWhat happens
0Success. If standard output is one JSON object, Claude Code reads it as instructions; otherwise it is plain text
2Blocking error. On events that can block, the action stops and the text on standard error becomes the reason Claude sees
Any other code, including 1Non-blocking error. The action goes ahead and a notice appears in the transcript

This is the most common mistake: exit 1 is the usual Unix failure code, but in a hook it does not stop anything. Use exit 2 to enforce a rule (hooks reference).

For finer control, print JSON on exit 0. On PreToolUse, hookSpecificOutput can set permissionDecision to allow, deny, ask or defer, with a permissionDecisionReason. additionalContext adds a note to Claude's context, and "continue": false stops Claude after the hook.

Which hooks are worth setting up first?

  1. Format or lint after edits: PostToolUse with the matcher Edit|Write, as in the example above. Claude sees the formatted file on its next read.
  2. Block dangerous commands: PreToolUse with the matcher Bash and the handler field "if": "Bash(rm *)" pointing to a script that exits 2 with a reason. The if field uses the same syntax as permission rules.
  3. Run the checks before Claude stops: a Stop hook that runs the type check and exits 2 with the errors when it fails, so Claude fixes them before handing back.

A Stop hook that always fails would keep Claude working, so make the script exit 0 once the check passes. The hook input has a stop_hook_active field that is true when Claude is already continuing because of a stop hook, and after eight continuations in a row Claude Code ends the turn anyway. Test each hook on a throwaway branch first. For when to reach for hooks against rules and skills, see Claude Code best practices.

What should you watch out for?

  • Command hooks run shell commands with your full user permissions, Anthropic warns. Read and test any hook before adding it, including hooks that arrive with a cloned repo or a plugin.
  • Matching hooks run in parallel, so do not rely on the order between two hooks on the same event.
  • Text a hook returns to Claude is capped at 10,000 characters. Longer output is saved to a file with a 2,000 character preview.
  • Files you add with @ are included without a tool call, so PreToolUse hooks do not run for them. A Read deny rule blocks those paths (common workflows).

Frequently asked questions

What are hooks in Claude Code?

Commands or other handlers that Claude Code runs automatically at set events, such as before a tool call or when Claude stops. They are defined in settings files under "hooks".

Where is the Claude Code hooks config file?

In a settings file: ~/.claude/settings.json for all projects, .claude/settings.json for a shared project setup, or .claude/settings.local.json for your own project settings.

How do I block a command with a hook?

Use a PreToolUse hook with the matcher Bash. The script exits with code 2 and writes the reason to standard error. Exit code 1 does not block.

How do I see which hooks are active?

Run /hooks. It lists every configured hook by source, and you can open one to see its command and file.

Can I turn hooks off?

Set "disableAllHooks": true in a settings file. There is no switch for a single hook; delete its entry instead. Hooks set by an organization's managed settings cannot be turned off from outside those settings.

Next guideClaude Code subagents →