Hooks reference - Claude Code Docs
Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. For a quickstart guide with examples, see Automate actions with hooks . Hooks are user-defined shell commands, HTTP endpoints, MCP tool calls, LLM prompts, or subagents that execute automatically at specific points in Claude Code’s lifecycle.
Claude Code fires the same hook events wherever it runs: sessions in the terminal, IDE extensions, the Desktop app , and cloud sessions . Use this reference to look up event schemas, configuration options, JSON input/output formats, and advanced features like async hooks, HTTP hooks, and MCP tool hooks. A plugin can also register hooks as JavaScript functions that Claude Code calls in its own process, which can draw in the interface as well as act on events.
A plugin that does is a mod , and those function hooks are covered in React to events rather than here. The hooks on this page keep working alongside mods. Hook lifecycle Claude Code runs hooks at specific points during a session. When an event fires and a matcher matches, Claude Code passes JSON context about the event to your hook handler. For command hooks, input arrives on stdin. For HTTP hooks, it arrives as the POST request body.
Your handler can then inspect the input, take action, and optionally return a decision. Events fall into three cadences: per session: SessionStart and SessionEnd per turn: UserPromptSubmit , Stop , and StopFailure on every tool call inside the agentic loop: PreToolUse and PostToolUse , except EndConversation calls, which skip both The table below summarizes when each event fires. The Hook events section documents the full input schema and decision control options for each one.
Event When it fires SessionStart When a session begins or resumes 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 UserPromptSubmit When a prompt is submitted, before Claude processes it. Also fires on turns Claude Code starts on its own UserPromptExpansion When a user-typed command expands into a prompt, before it reaches Claude.
Can block the expansion PreToolUse Before a tool call executes. Can block it PermissionRequest When a tool call needs a permission decision 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 PostToolUse After a tool call succeeds PostToolUseFailure After a tool call fails PostToolBatch After a full batch of parallel tool calls resolves, before the next model call Notification When Claude Code sends a notification MessageDisplay While assistant message text is displayed SubagentStart When a subagent is spawned SubagentStop When a subagent finishes TaskCreated When a task is being created via TaskCreate TaskCompleted When a task is being marked as completed Stop When Claude finishes responding StopFailure When the turn ends due to an API error TeammateIdle When an agent team teammate is about to go idle 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 ConfigChange When a configuration file changes during a session CwdChanged When the working directory changes, for example when Claude executes a cd command. Useful for reactive environment management with tools like direnv DirectoryAdded When a working directory is added mid-session via /add-dir or the SDK register_repo_root control request FileChanged When a watched file changes on disk.
The matcher field specifies which filenames to watch WorktreeCreate When a worktree is being created via --worktree , isolation: "worktree" , or for a background session. Replaces default git behavior WorktreeRemove When a worktree that a WorktreeCreate hook created is being removed PreCompact Before context compaction PostCompact After context compaction completes PreModelSwitch Before Claude Code applies a model switch that you or a client requested.
Can block the switch 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 Elicitation When an MCP server requests user input during a tool call ElicitationResult After a user responds to an MCP elicitation, before the response is sent back to the server SessionEnd When a session terminates How a hook resolves To see how the event, the matcher, and the handler fit together, consider this PreToolUse hook that blocks rm -rf commands. macOS/Linux Windows (PowerShell) The matcher narrows to Bash tool calls and Monitor commands , and the if condition narrows further to Bash subcommands matching rm * , so block-rm.sh only spawns when both filters match: { "hooks" : { "PreToolUse" : [ { "matcher" : "Bash" , "hooks" : [ { "type" : "command" , "if" : "Bash(rm *)" , "command" : "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh" , "args" : [] } ] } ] } } The script reads the JSON input from stdin, extracts the command, and returns a permissionDecision of "deny" if it contains rm -rf .
Save it to .claude/hooks/block-rm.sh in your project and make it executable with chmod +x .claude/hooks/block-rm.sh so Claude Code can run it: #!/bin/bash # .claude/hooks/block-rm.sh COMMAND = $( jq -r '.tool_input.command' ) if echo " $COMMAND " | grep -q 'rm -rf' ; then jq -n '{ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: "Destructive command blocked by hook" } }' else exit 0 # no decision; normal permission flow applies fi This script, like the other Bash examples on this page that parse JSON input, uses jq , so install jq and make sure it is on your PATH before trying them.
The matcher Bash|PowerShell covers the PowerShell tool as well as Bash. A single if rule names one tool, so each tool gets its own handler: the first narrows to Bash subcommands matching rm * , the second to PowerShell commands matching Remove-Item * . Both run the same script through powershell.exe : { "hooks" : { "PreToolUse" : [ { "matcher" : "Bash|PowerShell" , "hooks" : [ { "type" : "command" , "if" : "Bash(rm *)" , "command" : "powershell.exe" , "args" : [ "-NoProfile" , "-ExecutionPolicy" , "Bypass" , "-File" , "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1" ] }, { "type" : "command" , "if" : "PowerShell(Remove-Item *)" , "command" : "powershell.exe" , "args" : [ "-NoProfile" , "-ExecutionPolicy" , "Bypass" , "-File" , "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1" ] } ] } ] } } The -NoProfile flag skips loading your PowerShell profile so the hook starts fast, and -ExecutionPolicy Bypass lets PowerShell run the local script file.
The script reads the JSON input from stdin, extracts the command, and returns a permissionDecision of "deny" if it contains rm -rf or Remove-Item followed by -Recurse . Save it to .claude/hooks/block-rm.ps1 in your project: # .claude/hooks/block-rm.ps1 $callInput = [ Console ]:: In .ReadToEnd() | ConvertFrom-Json $command = $callInput .tool_input.command if ( $command -match 'rm -rf|Remove-Item.*-Recurse' ) { @ { hookSpecificOutput = @ { hookEventName = "PreToolUse" permissionDecision = "deny" permissionDecisionReason = "Destructive command blocked by hook" } } | ConvertTo-Json } else { exit 0 # no decision; normal permission flow applies } Now suppose Claude Code decides to run Bash "rm -rf /tmp/build" against the macOS/Linux config.
Here’s what happens: 1 Event fires The PreToolUse event fires. Claude Code sends the tool input as JSON on stdin to the hook: { "tool_name" : "Bash" , "tool_input" : { "command" : "rm -rf /tmp/build" }, ... } 2 Matcher checks The matcher
The rest of this page is on the live site.