Menu
Create and configure git hooks with intelligent project analysis, suggestions, and automated testing
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
Review your local uncommitted working-tree changes (git diff plus untracked files) and return actionable improvement suggestions. Use before committing, when nothing has been pushed yet.
Review an existing GitHub pull request and post inline review comments on its diff. Use when the changes are on an opened PR rather than your local working tree.
Add missing test coverage for your local code changes by generating new test files (covers uncommitted and untracked changes, or the latest commit if everything is committed). Use when you want write tests for new logic or increase test coverage.
Run independent tasks concurrently across multiple files or targets using parallel sub-agents, with per-task model selection and LLM-as-a-judge verification. Use when tasks do not depend on each other and can run side by side.
Execute one complex task as ordered, dependent steps run sequentially, passing context from each step to the next, with per-step LLM-as-a-judge verification. Use when later steps depend on the results of earlier ones.
Verify what PR review comments have been addressed (committed/pushed OR uncommitted local changes) and resolve the threads that are genuinely fixed or no longer relevant.
| name | create-hook |
| description | Create and configure git hooks with intelligent project analysis, suggestions, and automated testing |
| argument-hint | Optional hook type or description of desired behavior |
Analyze the project, suggest practical hooks, and create them with proper testing.
Automatically detect the project tooling and suggest relevant hooks:
When TypeScript is detected (tsconfig.json):
When Prettier is detected (.prettierrc, prettier.config.js):
When ESLint is detected (.eslintrc.*):
When package.json has scripts:
test script → "Run tests before commits"build script → "Validate build before commits"When a git repository is detected:
Decision Tree:
Project has TypeScript? → Suggest type checking hooks
Project has formatter? → Suggest formatting hooks
Project has tests? → Suggest test validation hooks
Security sensitive? → Suggest security hooks
+ Scan for additional patterns and suggest custom hooks based on:
- Custom scripts in package.json
- Unique file patterns or extensions
- Development workflow indicators
- Project-specific tooling configurations
Start by asking: "What should this hook do?" and offer relevant suggestions from your analysis.
Then understand the context from the user's description and only ask about details you're unsure about:
Trigger timing: When should it run?
PreToolUse: Before file operations (can block)PostToolUse: After file operations (feedback/fixes)UserPromptSubmit: Before processing requestsTool matcher: Which tools should trigger it? (Write, Edit, Bash, * etc)
Scope: global, project, or project-local
Response approach:
Blocking behavior (if relevant): "Should this stop operations when issues are found?"
Claude integration (CRITICAL): "Should Claude Code automatically see and fix issues this hook detects?"
additionalContext for error communicationsuppressOutput: true for silent operationContext pollution: "Should successful operations be silent to avoid noise?"
File filtering: "What file types should this hook process?"
You should:
~/.claude/hooks/ or .claude/hooks/ based on scope$CLAUDE_PROJECT_DIR to reference project rootKey Implementation Standards:
additionalContext/systemMessage for Claude communicationsuppressOutput: true for successful operations⚠️ CRITICAL: Input/Output Format
This is where most hook implementations fail. Pay extra attention to:
CRITICAL: Test both happy and sad paths:
Happy Path Testing:
Sad Path Testing: 2. Test expected failure scenario - Create conditions where hook should fail/warn
Verification Steps: 3. Verify expected behavior: Check if it blocks/warns/provides context as intended
Example Testing Process:
If Issues Occur, you should:
chmod +x)#!/usr/bin/env node
// Read stdin JSON, check .ts/.tsx files only
// Run: npx tsc --noEmit --pretty
// Output: JSON with additionalContext for errors
#!/usr/bin/env node
// Read stdin JSON, check supported file types
// Run: npx prettier --write [file]
// Output: JSON with suppressOutput: true
#!/bin/bash
# Read stdin JSON, check for secrets/keys
# Block if dangerous patterns found
# Exit 2 to block, 0 to continue
Complete templates available at: https://docs.claude.com/en/docs/claude-code/hooks#examples
📖 Official Docs: https://docs.claude.com/en/docs/claude-code/hooks.md
Common Patterns:
JSON.parse(process.stdin.read()){continue: true, suppressOutput: true}{continue: true, additionalContext: "error details"}exit(2) in PreToolUse hooksHook Types by Use Case:
Hook Execution Best Practices:
✅ Hook created successfully when:
Result: The user gets a working hook that enhances their development workflow with intelligent automation and quality checks.
Documentation Index
Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further.
Run shell commands automatically when Claude Code edits files, finishes tasks, or needs input. Format code, send notifications, validate commands, and enforce project rules.
Hooks are user-defined shell commands that execute at specific points in Claude Code's lifecycle. They provide deterministic control over Claude Code's behavior, ensuring certain actions always happen rather than relying on the LLM to choose to run them. Use hooks to enforce project rules, automate repetitive tasks, and integrate Claude Code with your existing tools.
For decisions that require judgment rather than deterministic rules, you can also use prompt-based hooks or agent-based hooks that use a Claude model to evaluate conditions.
For other ways to extend Claude Code, see skills for giving Claude additional instructions and executable commands, subagents for running tasks in isolated contexts, and plugins for packaging extensions to share across projects.
This guide covers common use cases and how to get started. For full event schemas, JSON input/output formats, and advanced features like async hooks and MCP tool hooks, see the [Hooks reference](/en/hooks).The fastest way to create a hook is through the /hooks interactive menu in Claude Code. This walkthrough creates a desktop notification hook, so you get alerted whenever Claude is waiting for your input instead of watching the terminal.
<Tabs>
<Tab title="macOS">
Uses [`osascript`](https://ss64.com/mac/osascript.html) to trigger a native macOS notification through AppleScript:
```
osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'
```
</Tab>
<Tab title="Linux">
Uses `notify-send`, which is pre-installed on most Linux desktops with a notification daemon:
```
notify-send 'Claude Code' 'Claude Code needs your attention'
```
</Tab>
<Tab title="Windows (PowerShell)">
Uses PowerShell to show a native message box through .NET's Windows Forms:
```
powershell.exe -Command "[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')"
```
</Tab>
</Tabs>
Hooks let you run code at key points in Claude Code's lifecycle: format files after edits, block commands before they execute, send notifications when Claude needs input, inject context at session start, and more. For the full list of hook events, see the Hooks reference.
Each example includes a ready-to-use configuration block that you add to a settings file. The most common patterns:
Get a desktop notification whenever Claude finishes working and needs your input, so you can switch to other tasks without checking the terminal.
This hook uses the Notification event, which fires when Claude is waiting for input or permission. Each tab below uses the platform's native notification command. Add this to ~/.claude/settings.json, or use the interactive walkthrough above to configure it with /hooks:
Automatically run Prettier on every file Claude edits, so formatting stays consistent without manual intervention.
This hook uses the PostToolUse event with an Edit|Write matcher, so it runs only after file-editing tools. The command extracts the edited file path with jq and passes it to Prettier. Add this to .claude/settings.json in your project root:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
}
]
}
]
}
}
Prevent Claude from modifying sensitive files like .env, package-lock.json, or anything in .git/. Claude receives feedback explaining why the edit was blocked, so it can adjust its approach.
This example uses a separate script file that the hook calls. The script checks the target file path against a list of protected patterns and exits with code 2 to block the edit.
Save this to `.claude/hooks/protect-files.sh`:```bash theme={null}
#!/bin/bash
# protect-files.sh
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")
for pattern in "${PROTECTED_PATTERNS[@]}"; do
if [[ "$FILE_PATH" == *"$pattern"* ]]; then
echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
exit 2
fi
done
exit 0
```
```bash theme={null}
chmod +x .claude/hooks/protect-files.sh
```
```json theme={null}
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
}
]
}
]
}
}
```
When Claude's context window fills up, compaction summarizes the conversation to free space. This can lose important details. Use a SessionStart hook with a compact matcher to re-inject critical context after every compaction.
Any text your command writes to stdout is added to Claude's context. This example reminds Claude of project conventions and recent work. Add this to .claude/settings.json in your project root:
{
"hooks": {
"SessionStart": [
{
"matcher": "compact",
"hooks": [
{
"type": "command",
"command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
}
]
}
]
}
}
You can replace the echo with any command that produces dynamic output, like git log --oneline -5 to show recent commits. For injecting context on every session start, consider using CLAUDE.md instead. For environment variables, see CLAUDE_ENV_FILE in the reference.
Hook events fire at specific lifecycle points in Claude Code. When an event fires, all matching hooks run in parallel, and identical hook commands are automatically deduplicated. The table below shows each event and when it triggers:
| Event | When it fires |
|---|---|
SessionStart | When a session begins or resumes |
UserPromptSubmit | When you submit a prompt, before Claude processes it |
PreToolUse | Before a tool call executes. Can block it |
PermissionRequest | When a permission dialog appears |
PostToolUse | After a tool call succeeds |
PostToolUseFailure | After a tool call fails |
Notification | When Claude Code sends a notification |
SubagentStart | When a subagent is spawned |
SubagentStop | When a subagent finishes |
Stop | When Claude finishes responding |
PreCompact | Before context compaction |
SessionEnd | When a session terminates |
Each hook has a type that determines how it runs. Most hooks use "type": "command", which runs a shell command. Two other options use a Claude model to make decisions: "type": "prompt" for single-turn evaluation and "type": "agent" for multi-turn verification with tool access. See Prompt-based hooks and Agent-based hooks for details.
Hooks communicate with Claude Code through stdin, stdout, stderr, and exit codes. When an event fires, Claude Code passes event-specific data as JSON to your script's stdin. Your script reads that data, does its work, and tells Claude Code what to do next via the exit code.
Every event includes common fields like session_id and cwd, but each event type adds different data. For example, when Claude runs a Bash command, a PreToolUse hook receives something like this on stdin:
{
"session_id": "abc123", // unique ID for this session
"cwd": "/Users/sarah/myproject", // working directory when the event fired
"hook_event_name": "PreToolUse", // which event triggered this hook
"tool_name": "Bash", // the tool Claude is about to use
"tool_input": { // the arguments Claude passed to the tool
"command": "npm test" // for Bash, this is the shell command
}
}
Your script can parse that JSON and act on any of those fields. UserPromptSubmit hooks get the prompt text instead, SessionStart hooks get the source (startup, resume, compact), and so on. See Common input fields in the reference for shared fields, and each event's section for event-specific schemas.
Your script tells Claude Code what to do next by writing to stdout or stderr and exiting with a specific code. For example, a PreToolUse hook that wants to block a command:
#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
if echo "$COMMAND" | grep -q "drop table"; then
echo "Blocked: dropping tables is not allowed" >&2 # stderr becomes Claude's feedback
exit 2 # exit 2 = block the action
fi
exit 0 # exit 0 = let it proceed
The exit code determines what happens next:
UserPromptSubmit and SessionStart hooks, anything you write to stdout is added to Claude's context.Ctrl+O to see these messages in the transcript.Exit codes give you two options: allow or block. For more control, exit 0 and print a JSON object to stdout instead.
Use exit 2 to block with a stderr message, or exit 0 with JSON for structured control. Don't mix them: Claude Code ignores JSON when you exit 2.For example, a PreToolUse hook can deny a tool call and tell Claude why, or escalate it to the user for approval:
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Use rg instead of grep for better performance"
}
}
Claude Code reads permissionDecision and cancels the tool call, then feeds permissionDecisionReason back to Claude as feedback. These three options are specific to PreToolUse:
"allow": proceed without showing a permission prompt"deny": cancel the tool call and send the reason to Claude"ask": show the permission prompt to the user as normalOther events use different decision patterns. For example, PostToolUse and Stop hooks use a top-level decision: "block" field, while PermissionRequest uses hookSpecificOutput.decision.behavior. See the summary table in the reference for a full breakdown by event.
For UserPromptSubmit hooks, use additionalContext instead to inject text into Claude's context. Prompt-based hooks (type: "prompt") handle output differently: see Prompt-based hooks.
Without a matcher, a hook fires on every occurrence of its event. Matchers let you narrow that down. For example, if you want to run a formatter only after file edits (not after every tool call), add a matcher to your PostToolUse hook:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "prettier --write ..." }
]
}
]
}
}
The "Edit|Write" matcher is a regex pattern that matches the tool name. The hook only fires when Claude uses the Edit or Write tool, not when it uses Bash, Read, or any other tool.
Each event type matches on a specific field. Matchers support exact strings and regex patterns:
| Event | What the matcher filters | Example matcher values |
|---|---|---|
PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest | tool name | Bash, Edit|Write, mcp__.* |
SessionStart | how the session started | startup, resume, clear, compact |
SessionEnd | why the session ended | clear, logout, prompt_input_exit, other |
Notification | notification type | permission_prompt, idle_prompt, auth_success, elicitation_dialog |
SubagentStart | agent type | Bash, Explore, Plan, or custom agent names |
PreCompact | what triggered compaction | manual, auto |
UserPromptSubmit, Stop | no matcher support | always fires on every occurrence |
SubagentStop | agent type | same values as SubagentStart |
A few more examples showing matchers on different event types:
Match only `Bash` tool calls and log each command to a file. The `PostToolUse` event fires after the command completes, so `tool_input.command` contains what ran. The hook receives the event data as JSON on stdin, and `jq -r '.tool_input.command'` extracts just the command string, which `>>` appends to the log file:```json theme={null}
{
"hooks": {
"PostToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
}
]
}
]
}
}
```
The command below extracts the tool name from the hook's JSON input with `jq` and writes it to stderr, where it shows up in verbose mode (`Ctrl+O`):
```json theme={null}
{
"hooks": {
"PreToolUse": [
{
"matcher": "mcp__github__.*",
"hooks": [
{
"type": "command",
"command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >&2"
}
]
}
]
}
}
```
```json theme={null}
{
"hooks": {
"SessionEnd": [
{
"matcher": "clear",
"hooks": [
{
"type": "command",
"command": "rm -f /tmp/claude-scratch-*.txt"
}
]
}
]
}
}
```
For full matcher syntax, see the Hooks reference.
Where you add a hook determines its scope:
| 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 |
| Managed policy settings | Organization-wide | Yes, admin-controlled |
Plugin hooks/hooks.json | When plugin is enabled | Yes, bundled with the plugin |
| Skill or agent frontmatter | While the skill or agent is active | Yes, defined in the component file |
You can also use the /hooks menu in Claude Code to add, delete, and view hooks interactively. To disable all hooks at once, use the toggle at the bottom of the /hooks menu or set "disableAllHooks": true in your settings file.
Hooks added through the /hooks menu take effect immediately. If you edit settings files directly while Claude Code is running, the changes won't take effect until you review them in the /hooks menu or restart your session.
For decisions that require judgment rather than deterministic rules, use type: "prompt" hooks. Instead of running a shell command, Claude Code sends your prompt and the hook's input data to a Claude model (Haiku by default) to make the decision. You can specify a different model with the model field if you need more capability.
The model's only job is to return a yes/no decision as JSON:
"ok": true: the action proceeds"ok": false: the action is blocked. The model's "reason" is fed back to Claude so it can adjust.This example uses a Stop hook to ask the model whether all requested tasks are complete. If the model returns "ok": false, Claude keeps working and uses the reason as its next instruction:
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "prompt",
"prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
}
]
}
]
}
}
For full configuration options, see Prompt-based hooks in the reference.
When verification requires inspecting files or running commands, use type: "agent" hooks. Unlike prompt hooks which make a single LLM call, agent hooks spawn a subagent that can read files, search code, and use other tools to verify conditions before returning a decision.
Agent hooks use the same "ok" / "reason" response format as prompt hooks, but with a longer default timeout of 60 seconds and up to 50 tool-use turns.
This example verifies that tests pass before allowing Claude to stop:
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "agent",
"prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
"timeout": 120
}
]
}
]
}
}
Use prompt hooks when the hook input data alone is enough to make a decision. Use agent hooks when you need to verify something against the actual state of the codebase.
For full configuration options, see Agent-based hooks in the reference.
timeout field (in seconds).PostToolUse hooks cannot undo actions since the tool has already executed.PermissionRequest hooks do not fire in non-interactive mode (-p). Use PreToolUse hooks for automated permission decisions.Stop hooks fire whenever Claude finishes responding, not only at task completion. They do not fire on user interrupts.The hook is configured but never executes.
/hooks and confirm the hook appears under the correct eventPreToolUse fires before tool execution, PostToolUse fires after)PermissionRequest hooks in non-interactive mode (-p), switch to PreToolUse insteadYou see a message like "PreToolUse hook error: ..." in the transcript.
Your script exited with a non-zero code unexpectedly. Test it manually by piping sample JSON:
echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
echo $? # Check the exit code
$CLAUDE_PROJECT_DIR to reference scriptsjq or use Python/Node.js for JSON parsingchmod +x ./my-hook.sh/hooks shows no hooks configuredYou edited a settings file but the hooks don't appear in the menu.
/hooks to reload. Hooks added through the /hooks menu take effect immediately, but manual file edits require a reload..claude/settings.json for project hooks, ~/.claude/settings.json for global hooksClaude keeps working in an infinite loop instead of stopping.
Your Stop hook script needs to check whether it already triggered a continuation. Parse the stop_hook_active field from the JSON input and exit early if it's true:
#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
exit 0 # Allow Claude to stop
fi
# ... rest of your hook logic
Claude Code shows a JSON parsing error even though your hook script outputs valid JSON.
When Claude Code runs a hook, it spawns a shell that sources your profile (~/.zshrc or ~/.bashrc). If your profile contains unconditional echo statements, that output gets prepended to your hook's JSON:
Shell ready on arm64
{"decision": "block", "reason": "Not allowed"}
Claude Code tries to parse this as JSON and fails. To fix this, wrap echo statements in your shell profile so they only run in interactive shells:
# In ~/.zshrc or ~/.bashrc
if [[ $- == *i* ]]; then
echo "Shell ready"
fi
The $- variable contains shell flags, and i means interactive. Hooks run in non-interactive shells, so the echo is skipped.
Toggle verbose mode with Ctrl+O to see hook output in the transcript, or run claude --debug for full execution details including which hooks matched and their exit codes.
Documentation Index
Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further.
For a quickstart guide with examples, see [Automate workflows with hooks](/en/hooks-guide).Reference for Claude Code hook events, configuration schema, JSON input/output formats, exit codes, async hooks, prompt hooks, and MCP tool hooks.
Hooks are user-defined shell commands or LLM prompts that execute automatically at specific points in Claude Code's lifecycle. Use this reference to look up event schemas, configuration options, JSON input/output formats, and advanced features like async hooks and MCP tool hooks. If you're setting up hooks for the first time, start with the guide instead.
Hooks fire at specific points during a Claude Code session. When an event fires and a matcher matches, Claude Code passes JSON context about the event to your hook handler. For command hooks, this arrives on stdin. Your handler can then inspect the input, take action, and optionally return a decision. Some events fire once per session, while others fire repeatedly inside the agentic loop:
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 |
UserPromptSubmit | When you submit a prompt, before Claude processes it |
PreToolUse | Before a tool call executes. Can block it |
PermissionRequest | When a permission dialog appears |
PostToolUse | After a tool call succeeds |
PostToolUseFailure | After a tool call fails |
Notification | When Claude Code sends a notification |
SubagentStart | When a subagent is spawned |
SubagentStop | When a subagent finishes |
Stop | When Claude finishes responding |
PreCompact | Before context compaction |
SessionEnd | When a session terminates |
To see how these pieces fit together, consider this PreToolUse hook that blocks destructive shell commands. The hook runs block-rm.sh before every Bash tool call:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": ".claude/hooks/block-rm.sh"
}
]
}
]
}
}
The script reads the JSON input from stdin, extracts the command, and returns a permissionDecision of "deny" if it contains rm -rf:
#!/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 # allow the command
fi
Now suppose Claude Code decides to run Bash "rm -rf /tmp/build". Here's what happens:
The `PreToolUse` event fires. Claude Code sends the tool input as JSON on stdin to the hook:
```json theme={null}
{ "tool_name": "Bash", "tool_input": { "command": "rm -rf /tmp/build" }, ... }
```
```json theme={null}
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Destructive command blocked by hook"
}
}
```
If the command had been safe (like `npm test`), the script would hit `exit 0` instead, which tells Claude Code to allow the tool call with no further action.
The Configuration section below documents the full schema, and each hook event section documents what input your command receives and what output it can return.
Hooks are defined in JSON settings files. The configuration has three levels of nesting:
PreToolUse or StopSee How a hook resolves above for a complete walkthrough with an annotated example.
This page uses specific terms for each level: **hook event** for the lifecycle point, **matcher group** for the filter, and **hook handler** for the shell command, prompt, or agent that runs. "Hook" on its own refers to the general feature.Where you define a hook determines its scope:
| 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 |
| Managed policy settings | Organization-wide | Yes, admin-controlled |
Plugin hooks/hooks.json | When plugin is enabled | Yes, bundled with the plugin |
| Skill or agent frontmatter | While the component is active | Yes, defined in the component file |
For details on settings file resolution, see settings. Enterprise administrators can use allowManagedHooksOnly to block user, project, and plugin hooks. See Hook configuration.
The matcher field is a regex string that filters when hooks fire. Use "*", "", or omit matcher entirely to match all occurrences. Each event type matches on a different field:
| Event | What the matcher filters | Example matcher values |
|---|---|---|
PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest | tool name | Bash, Edit|Write, mcp__.* |
SessionStart | how the session started | startup, resume, clear, compact |
SessionEnd | why the session ended | clear, logout, prompt_input_exit, bypass_permissions_disabled, other |
Notification | notification type | permission_prompt, idle_prompt, auth_success, elicitation_dialog |
SubagentStart | agent type | Bash, Explore, Plan, or custom agent names |
PreCompact | what triggered compaction | manual, auto |
SubagentStop | agent type | same values as SubagentStart |
UserPromptSubmit, Stop | no matcher support | always fires on every occurrence |
The matcher is a regex, so Edit|Write matches either tool and Notebook.* matches any tool starting with Notebook. The matcher runs against a field from the JSON input that Claude Code sends to your hook on stdin. For tool events, that field is tool_name. Each hook event section lists the full set of matcher values and the input schema for that event.
This example runs a linting script only when Claude writes or edits a file:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "/path/to/lint-check.sh"
}
]
}
]
}
}
UserPromptSubmit and Stop don't support matchers and always fire on every occurrence. If you add a matcher field to these events, it is silently ignored.
MCP server tools appear as regular tools in tool events (PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest), so you can match them the same way you match any other tool name.
MCP tools follow the naming pattern mcp__<server>__<tool>, for example:
mcp__memory__create_entities: Memory server's create entities toolmcp__filesystem__read_file: Filesystem server's read file toolmcp__github__search_repositories: GitHub server's search toolUse regex patterns to target specific MCP tools or groups of tools:
mcp__memory__.* matches all tools from the memory servermcp__.*__write.* matches any tool containing "write" from any serverThis example logs all memory server operations and validates write operations from any MCP server:
{
"hooks": {
"PreToolUse": [
{
"matcher": "mcp__memory__.*",
"hooks": [
{
"type": "command",
"command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"
}
]
},
{
"matcher": "mcp__.*__write.*",
"hooks": [
{
"type": "command",
"command": "/home/user/scripts/validate-mcp-write.py"
}
]
}
]
}
}
Each object in the inner hooks array is a hook handler: the shell command, LLM prompt, or agent that runs when the matcher matches. There are three types:
type: "command"): run a shell command. Your script receives the event's JSON input on stdin and communicates results back through exit codes and stdout.type: "prompt"): send a prompt to a Claude model for single-turn evaluation. The model returns a yes/no decision as JSON. See Prompt-based hooks.type: "agent"): spawn a subagent that can use tools like Read, Grep, and Glob to verify conditions before returning a decision. See Agent-based hooks.These fields apply to all hook types:
| Field | Required | Description |
|---|---|---|
type | yes | "command", "prompt", or "agent" |
timeout | no | Seconds before canceling. Defaults: 600 for command, 30 for prompt, 60 for agent |
statusMessage | no | Custom spinner message displayed while the hook runs |
once | no | If true, runs only once per session then is removed. Skills only, not agents. See Hooks in skills and agents |
In addition to the common fields, command hooks accept these fields:
| Field | Required | Description |
|---|---|---|
command | yes | Shell command to execute |
async | no | If true, runs in the background without blocking. See Run hooks in the background |
In addition to the common fields, prompt and agent hooks accept these fields:
| Field | Required | Description |
|---|---|---|
prompt | yes | Prompt text to send to the model. Use $ARGUMENTS as a placeholder for the hook input JSON |
model | no | Model to use for evaluation. Defaults to a fast model |
All matching hooks run in parallel, and identical handlers are deduplicated automatically. Handlers run in the current directory with Claude Code's environment. The $CLAUDE_CODE_REMOTE environment variable is set to "true" in remote web environments and not set in the local CLI.
Use environment variables to reference hook scripts relative to the project or plugin root, regardless of the working directory when the hook runs:
$CLAUDE_PROJECT_DIR: the project root. Wrap in quotes to handle paths with spaces.${CLAUDE_PLUGIN_ROOT}: the plugin's root directory, for scripts bundled with a plugin.```json theme={null}
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh"
}
]
}
]
}
}
```
This example runs a formatting script bundled with the plugin:
```json theme={null}
{
"description": "Automatic code formatting",
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
"timeout": 30
}
]
}
]
}
}
```
See the [plugin components reference](/en/plugins-reference#hooks) for details on creating plugin hooks.
In addition to settings files and plugins, hooks can be defined directly in skills and subagents using frontmatter. These hooks are scoped to the component's lifecycle and only run when that component is active.
All hook events are supported. For subagents, Stop hooks are automatically converted to SubagentStop since that is the event that fires when a subagent completes.
Hooks use the same configuration format as settings-based hooks but are scoped to the component's lifetime and cleaned up when it finishes.
This skill defines a PreToolUse hook that runs a security validation script before each Bash command:
---
name: secure-operations
description: Perform operations with security checks
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/security-check.sh"
---
Agents use the same format in their YAML frontmatter.
/hooks menuType /hooks in Claude Code to open the interactive hooks manager, where you can view, add, and delete hooks without editing settings files directly. For a step-by-step walkthrough, see Set up your first hook in the guide.
Each hook in the menu is labeled with a bracket prefix indicating its source:
[User]: from ~/.claude/settings.json[Project]: from .claude/settings.json[Local]: from .claude/settings.local.json[Plugin]: from a plugin's hooks/hooks.json, read-onlyTo remove a hook, delete its entry from the settings JSON file, or use the /hooks menu and select the hook to delete it.
To temporarily disable all hooks without removing them, set "disableAllHooks": true in your settings file or use the toggle in the /hooks menu. There is no way to disable an individual hook while keeping it in the configuration.
Direct edits to hooks in settings files don't take effect immediately. Claude Code captures a snapshot of hooks at startup and uses it throughout the session. This prevents malicious or accidental hook modifications from taking effect mid-session without your review. If hooks are modified externally, Claude Code warns you and requires review in the /hooks menu before changes apply.
Hooks receive JSON data via stdin and communicate results through exit codes, stdout, and stderr. This section covers fields and behavior common to all events. Each event's section under Hook events includes its specific input schema and decision control options.
All hook events receive these fields via stdin as JSON, in addition to event-specific fields documented in each hook event section:
| Field | Description |
|---|---|
session_id | Current session identifier |
transcript_path | Path to conversation JSON |
cwd | Current working directory when the hook is invoked |
permission_mode | Current permission mode: "default", "plan", "acceptEdits", "dontAsk", or "bypassPermissions" |
hook_event_name | Name of the event that fired |
For example, a PreToolUse hook for a Bash command receives this on stdin:
{
"session_id": "abc123",
"transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
"cwd": "/home/user/my-project",
"permission_mode": "default",
"hook_event_name": "PreToolUse",
"tool_name": "Bash",
"tool_input": {
"command": "npm test"
}
}
The tool_name and tool_input fields are event-specific. Each hook event section documents the additional fields for that event.
The exit code from your hook command tells Claude Code whether the action should proceed, be blocked, or be ignored.
Exit 0 means success. Claude Code parses stdout for JSON output fields. JSON output is only processed on exit 0. For most events, stdout is only shown in verbose mode (Ctrl+O). The exceptions are UserPromptSubmit and SessionStart, where stdout is added as context that Claude can see and act on.
Exit 2 means a blocking error. Claude Code ignores stdout and any JSON in it. Instead, stderr text is fed back to Claude as an error message. The effect depends on the event: PreToolUse blocks the tool call, UserPromptSubmit rejects the prompt, and so on. See exit code 2 behavior for the full list.
Any other exit code is a non-blocking error. stderr is shown in verbose mode (Ctrl+O) and execution continues.
For example, a hook command script that blocks dangerous Bash commands:
#!/bin/bash
# Reads JSON input from stdin, checks the command
command=$(jq -r '.tool_input.command' < /dev/stdin)
if [[ "$command" == rm* ]]; then
echo "Blocked: rm commands are not allowed" >&2
exit 2 # Blocking error: tool call is prevented
fi
exit 0 # Success: tool call proceeds
Exit code 2 is the way a hook signals "stop, don't do this." The effect depends on the event, because some events represent actions that can be blocked (like a tool call that hasn't happened yet) and others represent things that already happened or can't be prevented.
| Hook event | Can block? | What happens on exit 2 |
|---|---|---|
PreToolUse | Yes | Blocks the tool call |
PermissionRequest | Yes | Denies the permission |
UserPromptSubmit | Yes | Blocks prompt processing and erases the prompt |
Stop | Yes | Prevents Claude from stopping, continues the conversation |
SubagentStop | Yes | Prevents the subagent from stopping |
PostToolUse | No | Shows stderr to Claude (tool already ran) |
PostToolUseFailure | No | Shows stderr to Claude (tool already failed) |
Notification | No | Shows stderr to user only |
SubagentStart | No | Shows stderr to user only |
SessionStart | No | Shows stderr to user only |
SessionEnd | No | Shows stderr to user only |
PreCompact | No | Shows stderr to user only |
Exit codes let you allow or block, but JSON output gives you finer-grained control. Instead of exiting with code 2 to block, exit 0 and print a JSON object to stdout. Claude Code reads specific fields from that JSON to control behavior, including decision control for blocking, allowing, or escalating to the user.
You must choose one approach per hook, not both: either use exit codes alone for signaling, or exit 0 and print JSON for structured control. Claude Code only processes JSON on exit 0. If you exit 2, any JSON is ignored.Your hook's stdout must contain only the JSON object. If your shell profile prints text on startup, it can interfere with JSON parsing. See JSON validation failed in the troubleshooting guide.
The JSON object supports three kinds of fields:
continue work across all events. These are listed in the table below.decision and reason are used by some events to block or provide feedback.hookSpecificOutput is a nested object for events that need richer control. It requires a hookEventName field set to the event name.| Field | Default | Description |
|---|---|---|
continue | true | If false, Claude stops processing entirely after the hook runs. Takes precedence over any event-specific decision fields |
stopReason | none | Message shown to the user when continue is false. Not shown to Claude |
suppressOutput | false | If true, hides stdout from verbose mode output |
systemMessage | none | Warning message shown to the user |
To stop Claude entirely regardless of event type:
{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }
Not every event supports blocking or controlling behavior through JSON. The events that do each use a different set of fields to express that decision. Use this table as a quick reference before writing a hook:
| Events | Decision pattern | Key fields |
|---|---|---|
| UserPromptSubmit, PostToolUse, PostToolUseFailure, Stop, SubagentStop | Top-level decision | decision: "block", reason |
| PreToolUse | hookSpecificOutput | permissionDecision (allow/deny/ask), permissionDecisionReason |
| PermissionRequest | hookSpecificOutput | decision.behavior (allow/deny) |
Here are examples of each pattern in action:
Used by `UserPromptSubmit`, `PostToolUse`, `PostToolUseFailure`, `Stop`, and `SubagentStop`. The only value is `"block"` — to allow the action to proceed, omit `decision` from your JSON, or exit 0 without any JSON at all:```json theme={null}
{
"decision": "block",
"reason": "Test suite must pass before proceeding"
}
```
```json theme={null}
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Database writes are not allowed"
}
}
```
```json theme={null}
{
"hookSpecificOutput": {
"hookEventName": "PermissionRequest",
"decision": {
"behavior": "allow",
"updatedInput": {
"command": "npm run lint"
}
}
}
}
```
For extended examples including Bash command validation, prompt filtering, and auto-approval scripts, see What you can automate in the guide and the Bash command validator reference implementation.
Each event corresponds to a point in Claude Code's lifecycle where hooks can run. The sections below are ordered to match the lifecycle: from session setup through the agentic loop to session end. Each section describes when the event fires, what matchers it supports, the JSON input it receives, and how to control behavior through output.
Runs when Claude Code starts a new session or resumes an existing session. Useful for loading development context like existing issues or recent changes to your codebase, or setting up environment variables. For static context that does not require a script, use CLAUDE.md instead.
SessionStart runs on every session, so keep these hooks fast.
The matcher value corresponds to how the session was initiated:
| Matcher | When it fires |
|---|---|
startup | New session |
resume | --resume, --continue, or /resume |
clear | /clear |
compact | Auto or manual compaction |
In addition to the common input fields, SessionStart hooks receive source, model, and optionally agent_type. The source field indicates how the session started: "startup" for new sessions, "resume" for resumed sessions, "clear" after /clear, or "compact" after compaction. The model field contains the model identifier. If you start Claude Code with claude --agent <name>, an agent_type field contains the agent name.
{
"session_id": "abc123",
"transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
"cwd": "/Users/...",
"permission_mode": "default",
"hook_event_name": "SessionStart",
"source": "startup",
"model": "claude-sonnet-4-5-20250929"
}
Any text your hook script prints to stdout is added as context for Claude. In addition to the JSON output fields available to all hooks, you can return these event-specific fields:
| Field | Description |
|---|---|
additionalContext | String added to Claude's context. Multiple hooks' values are concatenated |
{
"hookSpecificOutput": {
"hookEventName": "SessionStart",
"additionalContext": "My additional context here"
}
}
SessionStart hooks have access to the CLAUDE_ENV_FILE environment variable, which provides a file path where you can persist environment variables for subsequent Bash commands.
To set individual environment variables, write export statements to CLAUDE_ENV_FILE. Use append (>>) to preserve variables set by other hooks:
#!/bin/bash
if [ -n "$CLAUDE_ENV_FILE" ]; then
echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
echo 'export DEBUG_LOG=true' >> "$CLAUDE_ENV_FILE"
echo 'export PATH="$PATH:./node_modules/.bin"' >> "$CLAUDE_ENV_FILE"
fi
exit 0
To capture all environment changes from setup commands, compare the exported variables before and after:
#!/bin/bash
ENV_BEFORE=$(export -p | sort)
# Run your setup commands that modify the environment
source ~/.nvm/nvm.sh
nvm use 20
if [ -n "$CLAUDE_ENV_FILE" ]; then
ENV_AFTER=$(export -p | sort)
comm -13 <(echo "$ENV_BEFORE") <(echo "$ENV_AFTER") >> "$CLAUDE_ENV_FILE"
fi
exit 0
Any variables written to this file will be available in all subsequent Bash commands that Claude Code executes during the session.
`CLAUDE_ENV_FILE` is available for SessionStart hooks. Other hook types do not have access to this variable.Runs when the user submits a prompt, before Claude processes it. This allows you to add additional context based on the prompt/conversation, validate prompts, or block certain types of prompts.
In addition to the common input fields, UserPromptSubmit hooks receive the prompt field containing the text the user submitted.
{
"session_id": "abc123",
"transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
"cwd": "/Users/...",
"permission_mode": "default",
"hook_event_name": "UserPromptSubmit",
"prompt": "Write a function to calculate the factorial of a number"
}
UserPromptSubmit hooks can control whether a user prompt is processed and add context. All JSON output fields are available.
There are two ways to add context to the conversation on exit code 0:
additionalContext: use the JSON format below for more control. The additionalContext field is added as contextPlain stdout is shown as hook output in the transcript. The additionalContext field is added more discretely.
To block a prompt, return a JSON object with decision set to "block":
| Field | Description |
|---|---|
decision | "block" prevents the prompt from being processed and erases it from context. Omit to allow the prompt to proceed |
reason | Shown to the user when decision is "block". Not added to context |
additionalContext | String added to Claude's context |
{
"decision": "block",
"reason": "Explanation for decision",
"hookSpecificOutput": {
"hookEventName": "UserPromptSubmit",
"additionalContext": "My additional context here"
}
}
Runs after Claude creates tool parameters and before processing the tool call. Matches on tool name: Bash, Edit, Write, Read, Glob, Grep, Task, WebFetch, WebSearch, and any MCP tool names.
Use PreToolUse decision control to allow, deny, or ask for permission to use the tool.
In addition to the common input fields, PreToolUse hooks receive tool_name, tool_input, and tool_use_id. The tool_input fields depend on the tool:
Executes shell commands.
| Field | Type | Example | Description |
|---|---|---|---|
command | string | "npm test" | The shell command to execute |
description | string | "Run test suite" | Optional description of what the command does |
timeout | number | 120000 | Optional timeout in milliseconds |
run_in_background | boolean | false | Whether to run the command in background |
Creates or overwrites a file.
| Field | Type | Example | Description |
|---|---|---|---|
file_path | string | "/path/to/file.txt" | Absolute path to the file to write |
content | string | "file content" | Content to write to the file |
Replaces a string in an existing file.
| Field | Type | Example | Description |
|---|---|---|---|
file_path | string | "/path/to/file.txt" | Absolute path to the file to edit |
old_string | string | "original text" | Text to find and replace |
new_string | string | "replacement text" | Replacement text |
replace_all | boolean | false | Whether to replace all occurrences |
Reads file contents.
| Field | Type | Example | Description |
|---|---|---|---|
file_path | string | "/path/to/file.txt" | Absolute path to the file to read |
offset | number | 10 | Optional line number to start reading from |
limit | number | 50 | Optional number of lines to read |
Finds files matching a glob pattern.
| Field | Type | Example | Description |
|---|---|---|---|
pattern | string | "**/*.ts" | Glob pattern to match files against |
path | string | "/path/to/dir" | Optional directory to search in. Defaults to current working directory |
Searches file contents with regular expressions.
| Field | Type | Example | Description |
|---|---|---|---|
pattern | string | "TODO.*fix" | Regular expression pattern to search for |
path | string | "/path/to/dir" | Optional file or directory to search in |
glob | string | "*.ts" | Optional glob pattern to filter files |
output_mode | string | "content" | "content", "files_with_matches", or "count". Defaults to "files_with_matches" |
-i | boolean | true | Case insensitive search |