Claude Code Hooks - Official Guide

Complete official documentation from https://code.claude.com/docs/en/hooks-guide

Automate workflows with hooks

Run shell commands automatically when Claude Code edits files, finishes tasks, or needs input. Format code, send notifications, validate commands, and enforce project rules.

Hook lifecycle

Hooks fire at specific points during a Claude Code session. The official hook events are:

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

Hook handler types

There are three types of hook handlers:

Command hooks (type: "command"): Run a shell command
Prompt hooks (type: "prompt"): Use Claude model for single-turn evaluation
Agent hooks (type: "agent"): Spawn subagent with tool access

Configuration structure

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolName|AnotherTool",
        "hooks": [
          {
            "type": "command",
            "command": "bash /path/to/script.sh",
            "timeout": 600,
            "async": false
          }
        ]
      }
    ]
  }
}

Hook input (stdin)

Common fields for all events:

session_id: Current session ID
transcript_path: Path to conversation JSON
cwd: Current working directory
permission_mode: Current permission mode
hook_event_name: Name of the event that fired

Event-specific fields depend on the event type.

Hook output (exit codes and stdout)

Exit 0: Success. Parse stdout for JSON decision
Exit 2: Blocking error. stderr text becomes Claude's feedback
Any other code: Non-blocking error

Tool matchers

Available for: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest

Tool names:

Built-in: Bash, Edit, Write, Read, Glob, Grep, Task, WebFetch, WebSearch
MCP tools: mcp__<server>__<tool> (e.g., mcp__github__search_repositories)

Event matchers

Different events match on different fields:

SessionStart: startup, resume, clear, compact
SessionEnd: clear, logout, prompt_input_exit, bypass_permissions_disabled, other
Notification: permission_prompt, idle_prompt, auth_success, elicitation_dialog
SubagentStart/SubagentStop: agent type (e.g., Bash, Explore, Plan)
PreCompact: manual, auto

Hook configuration locations

Location	Scope
`~/.claude/settings.json`	All your projects
`.claude/settings.json`	Single project
`.claude/settings.local.json`	Single project (gitignored)
Plugin `hooks/hooks.json`	When plugin enabled
Skill/Agent frontmatter	While component active

Best practices

✅ DO:

Use command hooks for deterministic actions
Use prompt hooks for judgment-based decisions
Use agent hooks when verification requires file inspection
Quote all shell variables: "$VAR"
Use absolute paths with $CLAUDE_PROJECT_DIR
Set appropriate timeouts
Use async hooks for long-running operations
Keep hooks fast (< 10 seconds by default)

❌ DON'T:

Trust input data blindly
Use relative paths
Put sensitive data in hook output
Create infinite loops in Stop hooks
Run blocking operations without async

See https://code.claude.com/docs/en/hooks-guide for complete guide See https://code.claude.com/docs/en/hooks for reference documentation

4.4 KiB Raw Permalink Blame History