Hooks | Claude Code

▾

Configuration

Location: .claude/settings.json in the project root.

Schema

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [{"type": "command", "command": "your-script"}]
      }
    ]
  }
}

Outer "hooks" wrapper required
matcher is tool name (case-sensitive): Edit, Write, Bash
Use "matcher": "" or "*" to match all tools

▾

Hook Input

Command receives JSON on stdin:

Field	Description
`session_id`	Session UUID
`cwd`	Current working directory
`hook_event_name`	Event type (e.g., "PostToolUse")
`tool_name`	Tool that was called
`tool_input`	Tool call arguments
`tool_response`	Tool call response
`tool_use_id`	Unique tool use ID

▾

Exit Codes (Critical)

This is the only way to give Claude feedback:

Exit Code	Behavior
0	Silent success. Claude does NOT see stdout.
2	Blocking error. stderr shown to Claude immediately.
Other	Non-blocking error. stderr shown to user only.

Important

Exit code 2 + stderr is the ONLY way for Claude to see hook output. Exit 0 is completely silent.

▾

Available Events

Event	When
`PreToolUse`	Before tool execution (can block)
`PostToolUse`	After tool completion
`PostToolUseFailure`	After tool fails
`Notification`	When notifications sent
`UserPromptSubmit`	When user submits prompt
`Stop`	When agent finishes
`SubagentStop`	When subagent finishes
`SessionStart`	Session begins
`SessionEnd`	Session terminates

▾

Environment Variables

$CLAUDE_PROJECT_DIR - Absolute path to project root
$CLAUDE_TOOL_INPUT_FILE_PATH - For Edit/Write, the file path being modified

▾

Gotchas

Settings must be in actual project root, not subdirectory
Hooks snapshot at session start - changes need /hooks command or session restart
PostToolUse can't block - tool already executed. Use PreToolUse to prevent.
Exit 0 gives NO feedback to Claude