Claude Code Hooks Guide — Automation & Workflow Setup

8 min read · Claude Code configuration

Hooks let you automate workflows in Claude Code by triggering actions at specific moments: before a tool runs, after it completes, or when Claude stops and waits for input. With hooks, you can enforce rules (block commits to main), run quality checks automatically (tests after every file change), or surface warnings before risky operations (file deletion).

Hooks live in your settings.json and execute through your machine, not Claude. They're reliable, fast, and under your control. For the full shape of that file — scopes, precedence, and the other top-level keys — see the settings.json guide.

How hooks work

A hook has three parts:

• 1. An event — when the hook fires (PreToolUse, PostToolUse, Stop)
• 2. A matcher — which tool or operation triggers it (Bash, Write, Edit, Delete)
• 3. An action — the command that runs (echo a warning, run your test suite, cancel the operation)

Hooks are defined in JSON inside one of six possible locations — ~/.claude/settings.json for global rules, .claude/settings.json for project rules you commit to the repo, .claude/settings.local.json for machine-specific overrides, managed-policy settings for org-wide enforcement, plugin bundles, and skill or agent frontmatter. The full locations table below covers precedence. The harness that runs Claude Code executes hooks, so they work reliably even if Claude tries to bypass them.

Example 1: Block commits to main

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git commit.*)",
        "hooks": [
          {
            "type": "command",
            "command": "if git rev-parse --verify HEAD 2>/dev/null && [[ $(git rev-parse --abbrev-ref HEAD) =~ ^(main|master)$ ]]; then echo '❌ Cannot commit directly to main/master. Create a feature branch first.'; exit 1; fi"
          }
        ]
      }
    ]
  }
}

Example 2: Run tests after file changes

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "if [ -f package.json ]; then npm test -- --run 2>&1 | head -50; elif [ -f pytest.ini ] || [ -f pyproject.toml ]; then python -m pytest --tb=short -q 2>&1 | head -50; fi"
          }
        ]
      }
    ]
  }
}

Example 3: Show git status when Claude stops

{
  "hooks": {
    "Stop": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "echo '\\n━━━ Git Status ━━━'; git status --short 2>/dev/null || echo 'Not a git repo'"
          }
        ]
      }
    ]
  }
}

Example 4: Warn before file deletion

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(rm|rmdir|git rm)",
        "hooks": [
          {
            "type": "command",
            "command": "echo '⚠️  WARNING: About to delete file(s). Confirm this was intentional.' && read -p 'Continue? (y/N): ' -n 1 response && [[ $response == 'y' ]] || exit 1"
          }
        ]
      }
    ]
  }
}

Example 5: Audit all tool calls to a log file

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "mkdir -p \"$CLAUDE_PROJECT_DIR/.claude\" && INPUT=$(cat); T=$(echo \"$INPUT\" | jq -r '.tool_name'); echo \"$(date '+%Y-%m-%d %H:%M:%S') | $T\" >> \"$CLAUDE_PROJECT_DIR/.claude/tool-audit.log\""
          }
        ]
      }
    ]
  }
}

Hook events, matchers, and handler types

Events

Claude Code ships more than two dozen hook events. The three you'll reach for 90% of the time:

• PreToolUse — Before a tool runs (block risky operations, ask for confirmation)
• PostToolUse — After a tool succeeds (run cleanup, tests, formatting)
• Stop — When Claude finishes a response and waits for input (show context, status)

Other events worth knowing: SessionStart and SessionEnd (session lifecycle), UserPromptSubmit (before Claude processes your prompt), PostToolUseFailure (only fires when a tool errored), SubagentStart / SubagentStop (for teammate agents), PreCompact / PostCompact (context compaction), FileChanged (watched file changed on disk), and CwdChanged. The authoritative list lives at the official hooks reference — Anthropic has been adding events every few releases, so check the docs before you bet a workflow on an event name you remember.

Matchers (which tools trigger the hook)

• Bash — All shell commands (or Bash(pattern) for specific commands)
• Write — File creation
• Edit|MultiEdit — File modification
• Read — File reading
• .* — Any tool (for broad logging)

Hook handler types

Each hook entry has a type field with four options:

• command — Run a shell command (the examples above). The workhorse type.
• http — POST the hook payload to a URL. Good for server-backed policy enforcement across a team.
• prompt — Feed text back into Claude's context at the hook point. Useful for reminders.
• agent — Spawn a subagent to handle the hook. For advanced workflows that need LLM judgment.

Best practices

Keep hook commands fast

If a hook takes > 5 seconds, Claude's workflow becomes annoying. Run quick checks, not full test suites.

Use PreToolUse to block, PostToolUse to inform

PreToolUse hooks that exit with error code 1 will block the operation. PostToolUse hooks run after success, so they can't prevent the operation but can inform you (tests failed, formatting done, etc.).

Prefer project-specific hooks for constraints

Put hooks that enforce project rules (no commits to main, no .env writes) in .claude/settings.json at the project root so they're version-controlled and shared with your team. Put personal preference hooks (show git status, format code) in ~/.claude/settings.json globally.

Where hooks can live

Hooks can be defined in six different places. The mental model is additive, not override: Claude Code merges hook arrays across scopes, so a PreToolUse hook in your user settings and a PreToolUse hook in a plugin will both run. Managed policy settings are the exception — they can restrict which scopes are allowed to load hooks in the first place, and disableAllHooks set at the managed level overrides disableAllHooks anywhere else. Run /hooks inside Claude Code to see every source currently active.

INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
CWD=$(echo "$INPUT" | jq -r '.cwd')

Debugging hooks

If a hook isn't working, check that your JSON is valid (use jq to parse .claude/settings.json), confirm the settings file location is correct, and test the matcher pattern — try a broad one first like .*.

Hooks should be reliable, but if something goes wrong, you can temporarily disable all hooks by adding "disableAllHooks": true to your settings.json, then reload Claude Code.

Frequently asked questions

Related reading: the MCP servers guide for how hooks layer on top of MCP tool calls, and the CLAUDE.md guide for how project rules load before hooks fire.