Claude Code Hooks: The Extensibility Feature That Makes It Programmable

Why Hooks Are the Killer Feature

The distinction matters. VS Code extensions customize your editor. GitHub Actions customize your CI. Claude Code hooks customize your AI agent. They turn a general-purpose coding assistant into a domain-specific development partner that enforces your team's rules, integrates with your infrastructure, and never forgets a step.

Unlike CLAUDE.md instructions which are advisory and may be ignored during long sessions, hooks are deterministic. They execute every time, guaranteed. This is the critical distinction:

The Three Hook Types

Every hook is one of three types, each suited to different levels of decision complexity.

Choose command hooks for anything deterministic (formatting, blocking, logging). Choose prompt hooks when the decision requires judgment but no file access. Choose agent hooks when verification requires inspecting the actual codebase state.

Hook Events: The Complete Lifecycle

Hooks fire at 14 different lifecycle events. Each corresponds to a specific moment in Claude's execution where you can inject custom behavior. The four most commonly used events are highlighted.

Matchers: Filtering When Hooks Fire

Without a matcher, a hook fires on every occurrence of its event. Matchers are regex strings that narrow this down. Use "*", "", or omit the matcher to match everything.

How Hooks Work: Input, Output, Exit Codes

Every hook receives JSON context via stdin when it fires. Your script reads this data, takes action, and tells Claude Code what to do next.

JSON Input

{
  "session_id": "abc123",
  "cwd": "/Users/dev/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

Exit Codes

Structured JSON Output

For more control than exit codes alone, exit 0 and print JSON to stdout. PreToolUse hooks can return permissionDecision (allow/deny/ask). PostToolUse and Stop hooks can return decision: "block" with a reason.

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep for performance"
  }
}

The Security Angle: Programmable Guardrails

When VS Code 1.109 introduced terminal sandboxing in late 2025 to prevent AI agents from running dangerous commands, it validated a problem Claude Code users had already solved with hooks. But hooks go far beyond sandboxing.

Hooks are programmable security policies, not just a blocklist. You write the logic. You decide what gets blocked, what gets logged, and what requires human confirmation. This is the level of control that makes teams comfortable running Claude Code in autonomous mode on production codebases.

#!/bin/bash
# .claude/hooks/security-guard.sh
# Programmable security policy — block destructive commands,
# require review for sensitive operations

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
TOOL=$(echo "$INPUT" | jq -r '.tool_name')

# Block destructive shell commands
if [ "$TOOL" = "Bash" ]; then
  if echo "$COMMAND" | grep -qE 'rm -rf|git push --force|drop table|truncate'; then
    echo "BLOCKED: destructive command not allowed" >&2
    exit 2
  fi
  # Log all shell commands to audit trail
  echo "$(date -u +%FT%TZ) BASH: $COMMAND" >> .claude/audit.log
fi

# Protect sensitive files from edits
if [ "$TOOL" = "Edit" ] || [ "$TOOL" = "Write" ]; then
  if echo "$FILE_PATH" | grep -qE '\.env|migrations/|package-lock\.json|\.git/'; then
    echo "BLOCKED: $FILE_PATH is a protected file" >&2
    exit 2
  fi
fi

exit 0

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/security-guard.sh"
          }
        ]
      }
    ]
  }
}

Auto-Format, Block, Notify: Core Patterns

These are the three hooks every Claude Code user should set up on day one. They eliminate the most common friction points.

Typecheck on Every Commit (Recommended)

The highest-value hook you can add today. bun run typecheck:fast uses tsgo (the native TypeScript type checker) to catch type errors in under a second. Run it as a Stop hook so Claude cannot finish a task with broken types.

// .claude/settings.json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "#!/bin/bash\nINPUT=$(cat)\nif [ \"$(echo \"$INPUT\" | jq -r '.stop_hook_active')\" = \"true\" ]; then exit 0; fi\nbun run typecheck:fast 2>&1 || { echo 'Type errors found. Fix before finishing.' >&2; exit 2; }"
          }
        ]
      }
    ]
  }
}

Pair this with a CLAUDE.md instruction to push to branches:

# Workflow
- IMPORTANT: Always push to a branch, never directly to main
- Run `bun run typecheck:fast` after every series of code changes
- Create a PR for review — do not merge directly

Auto-Format After Every Edit

The most popular hook in the community. AI-generated code instantly matches your project's style guide without relying on Claude to remember formatting rules.

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write 2>/dev/null"
          }
        ]
      }
    ]
  }
}

Desktop Notifications

Stop watching the terminal. Get alerted when Claude needs input so you can focus on other work.

// ~/.claude/settings.json (applies to all projects)
{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Stop Hooks as Quality Gates

Stop hooks fire when Claude finishes responding. They can prevent Claude from stopping if conditions are not met. This turns "please remember to run tests" from an advisory suggestion into an enforced requirement.

#!/bin/bash
# .claude/hooks/require-tests.sh

INPUT=$(cat)

# CRITICAL: Check stop_hook_active to prevent infinite loops
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Already continued once — let Claude stop
fi

# Run tests
if ! npm test 2>&1; then
  echo "Tests failing. Fix before finishing." >&2
  exit 2  # Block Claude from stopping
fi

exit 0

Stop hooks are where hooks become genuinely transformational. They implement what the community calls "quality gates" — automated checks that run every time Claude says it is done. Combined with best practices for task scoping, they close the loop on the "80% problem" where AI solutions are almost right but not quite.

Prompt and Agent-Based Hooks

Not every decision can be made with a shell script. For decisions that require judgment, use prompt or agent hooks.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all requested
tasks are complete. If not,
respond with {\"ok\": false,
\"reason\": \"what remains\"}."
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify all unit tests
pass. Run the test suite
and check results.
$ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Both types return the same format: {"ok": true} to allow the action, or {"ok": false, "reason": "..."} to block it. Use prompt hooks when the input data alone is enough to decide. Use agent hooks when you need to verify against the actual state of the codebase.

Hook + MCP Integration

This is where hooks become truly powerful. MCP (Model Context Protocol) servers give Claude access to external tools — databases, APIs, search engines. Hooks let you add guardrails, logging, and automation around those MCP tools.

MCP tools follow the naming pattern mcp__server__tool. Use regex matchers to target specific servers or operations.

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__github__.*",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '"GITHUB: " + .tool_name + " " + (.tool_input | tostring)' >> .claude/mcp-audit.log"
          }
        ]
      }
    ]
  }
}

// .claude/settings.json — Hook + MCP integration example
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "mcp__warpgrep__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Search complete. Results injected into context.' >> .claude/search.log",
            "async": true
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "mcp__.*__write.*|mcp__.*__delete.*|mcp__.*__create.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'MCP write operation detected — logging for audit' >> .claude/mcp-audit.log"
          }
        ]
      }
    ]
  }
}

Domain-Specific Automation

Hooks stop being "a feature" and become transformational when you realize they can encode your domain's rules. Claude Code is not just a coding assistant — with hooks, it becomes your coding assistant, shaped to your industry's exact requirements.

#!/bin/bash
# .claude/hooks/hipaa-guard.sh
# Block writes to files that may contain PHI patterns

INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name')
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

if [ "$TOOL" = "Edit" ] || [ "$TOOL" = "Write" ]; then
  # Check if file is in protected patient data directories
  if echo "$FILE_PATH" | grep -qE 'patient_data/|phi/|medical_records/'; then
    echo "BLOCKED: PHI directory requires manual review" >&2
    exit 2
  fi

  # Check file content for SSN/MRN patterns before allowing write
  if [ -f "$FILE_PATH" ]; then
    if grep -qE '[0-9]{3}-[0-9]{2}-[0-9]{4}|MRN-[0-9]+' "$FILE_PATH"; then
      echo "BLOCKED: File contains potential PHI patterns" >&2
      exit 2
    fi
  fi
fi

# Log all operations for compliance
echo "$(date -u +%FT%TZ) $TOOL: $FILE_PATH" >> .claude/hipaa-audit.log
exit 0

Advanced Patterns

Async Hooks for Background Tasks

Set "async": true to run a hook in the background. Claude continues working while the hook executes. Results are delivered on the next conversation turn.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-tests-async.sh",
            "async": true,
            "timeout": 300
          }
        ]
      }
    ]
  }
}

Context Re-Injection After Compaction

When Claude's context is compacted, important details can be lost. A SessionStart hook with a compact matcher re-injects critical context automatically.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'REMINDER: Use Bun, not npm. Run bun test before commits. Current sprint: auth refactor. See CLAUDE.md for full context.'"
          }
        ]
      }
    ]
  }
}

Persist Environment Variables

SessionStart hooks have access to CLAUDE_ENV_FILE. Write export statements to this file and they are available in all subsequent Bash commands.

#!/bin/bash
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=development' >> "$CLAUDE_ENV_FILE"
  echo 'export DEBUG_LOG=true' >> "$CLAUDE_ENV_FILE"
  echo "export PROJECT_ROOT=$(pwd)" >> "$CLAUDE_ENV_FILE"
fi
exit 0

Hooks in Skills and Agent Frontmatter

Hooks defined in skill or agent YAML frontmatter are scoped to that component's lifecycle. They only run while the skill/agent is active and are cleaned up when it finishes. This is ideal for security checks or validation that only applies during specific workflows.

Configuration Reference

Hooks live in JSON settings files with three levels of nesting: event, matcher group, and handler.

{
  "hooks": {
    "PostToolUse": [          // 1. Hook event
      {
        "matcher": "Edit|Write", // 2. Matcher (regex)
        "hooks": [              // 3. Handler(s)
          {
            "type": "command",
            "command": "npx prettier --write $(jq -r '.tool_input.file_path')"
          }
        ]
      }
    ]
  }
}

Where to Store Hooks

The fastest way to create a hook is the /hooks interactive menu. Type /hooks in Claude Code to view, add, and delete hooks without editing JSON directly. You can also ask Claude: "Write a hook that runs eslint after every file edit."

Frequently Asked Questions

What are Claude Code hooks?

Claude Code hooks are user-defined shell commands or LLM prompts that execute automatically at specific points in Claude Code's lifecycle. They provide deterministic control — unlike CLAUDE.md which is advisory, hooks guarantee the action happens every time. They are the extensibility feature that makes Claude Code programmable, letting you enforce security policies, automate formatting, and build domain-specific workflows.

How do I set up my first Claude Code hook?

Type /hooks in Claude Code to open the interactive menu. Select an event, set a matcher, and enter a shell command. You can also add hooks manually to .claude/settings.json or ask Claude: "Write a hook that runs eslint after every file edit."

What is the difference between PreToolUse and PostToolUse hooks?

PreToolUse runs before Claude executes a tool and can block it (exit code 2). Ideal for security guards. PostToolUse runs after a tool completes and cannot undo actions. Ideal for formatting, testing, and logging.

How do Claude Code hooks compare to VS Code terminal sandboxing?

VS Code 1.109 introduced terminal sandboxing with a fixed blocklist. Claude Code hooks provide the same safety but are programmable — custom logic per project, per directory, with audit logging, external API integration, and three-way allow/deny/ask decisions. Hooks are proactive policies where sandboxing is reactive blocking.

How do I prevent a Stop hook from running forever?

Check the stop_hook_active field in the JSON input. When it is true, exit 0 immediately to let Claude stop. Without this check, the hook creates an infinite loop. This is the most common mistake new hook authors make.

Can I use hooks with MCP tools?

Yes. MCP tools follow the naming pattern mcp__server__tool. Use regex matchers like mcp__github__.* to match all tools from a specific server, or mcp__.*__write.* to match write operations across all servers.

What is the recommended typecheck hook for TypeScript projects?

Use bun run typecheck:fast with tsgo (the native Go port of the TypeScript type checker) as a Stop hook. It completes in under a second — fast enough to run on every commit. Traditional tsc takes 10-30 seconds and is too slow for a commit hook. Add "typecheck:fast": "tsgo --noEmit" to your package.json scripts. Pair this with a CLAUDE.md instruction to always push to a branch, never directly to main.

Can Claude Code hooks run asynchronously?

Yes. Set "async": true on a command hook. Claude continues working while the hook runs in the background. Results are delivered on the next conversation turn. Async hooks cannot block actions since the triggering action has already completed.

How do hooks enable domain-specific automation?

Hooks encode your domain's rules as deterministic guardrails. Healthcare teams enforce HIPAA compliance on every file write. Fintech teams require security review for payment code. Game studios auto-run asset pipelines after shader edits. Combined with MCP servers for domain-specific tools, hooks transform Claude Code from a general-purpose assistant into a domain-specific development partner.