hooks-reference

Claude Code Hooks Reference

Hooks are user-defined shell commands that execute at various points in Claude Code's lifecycle, providing deterministic control over behavior.

Quick Reference: Hook Events

Event	When	Input	Can Control
PreToolUse	Before tool runs	Tool name, inputs	Block/modify tool
PostToolUse	After tool succeeds	Tool name, result	Feedback to Claude
PostToolUseFailure	After tool fails	Tool name, error	Error handling
PermissionRequest	Permission dialog shown	Details	Allow/deny
UserPromptSubmit	User submits prompt	User input	Modify prompt
Notification	Notification sent	Message	Custom notifications
Stop	Claude stops	Reason	Continue/stop
SubagentStop	Subagent completes	Result	Subagent behavior
PreCompact	Before compaction	Context	Modify context
SessionStart	Session begins	Session info	Env setup
SessionEnd	Session ends	Stats	Cleanup

Hook Configuration Location

~/.claude/settings.json          # User-level (all projects)
.claude/settings.json            # Project-level (team shared)
.claude/settings.local.json      # Project-local (gitignored)

Basic Hook Structure

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "your-script.sh"
          }
        ]
      }
    ]
  }
}

Matcher Patterns

Pattern	Matches
*	All tools
Bash	Bash tool only
Write|Edit	Write or Edit tools
Read.*	Read and any Read variants

Hook Types

Command Hook

{
  "type": "command",
  "command": "jq '.tool_input' >> /tmp/log.txt"
}

Prompt Hook

{
  "type": "prompt",
  "prompt": "Review the output: $ARGUMENTS"
}

Agent Hook

{
  "type": "agent",
  "prompt": "Verify the changes meet security requirements"
}

Control Flow via Exit Codes

Exit Code	Effect
0	Success, continue
2	Block (PreToolUse only)
Non-zero	Error, continue with warning

Hook Output Format (stdout JSON)

{
  "continue": true,
  "decision": "approve",
  "reason": "Looks good",
  "suppressOutput": false
}

Common Patterns

Auto-format on file write

{
  "PostToolUse": [{
    "matcher": "Write|Edit",
    "hooks": [{
      "type": "command",
      "command": "jq -r '.tool_input.file_path' | xargs prettier --write"
    }]
  }]
}

Block sensitive file edits

{
  "PreToolUse": [{
    "matcher": "Write|Edit",
    "hooks": [{
      "type": "command",
      "command": "jq -e '.tool_input.file_path | test(\"\\\\.env|\\\\.git\")' && exit 2 || exit 0"
    }]
  }]
}

Log all Bash commands

{
  "PreToolUse": [{
    "matcher": "Bash",
    "hooks": [{
      "type": "command",
      "command": "jq -r '.tool_input.command' >> ~/.claude/bash-log.txt"
    }]
  }]
}

Environment Variables in Hooks

Variable	Value
CLAUDE_PROJECT_DIR	Project root directory
CLAUDE_PLUGIN_ROOT	Plugin installation path

Debugging Hooks

# View loaded hooks
/hooks

# Test hook manually with sample input
echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | your-hook.sh

# Check exit code
echo $?

Security Considerations

• Hooks run with your credentials
• Validate all input before use
• Don't log sensitive data
• Use absolute paths for scripts
• Test hooks in isolation first

---

For complete documentation including all event schemas, see:

• hooks-full.md - Complete hooks reference
• hooks-howto.md - Step-by-step tutorials