Claude Code Hooks

What are Claude Code hooks?

Hooks let you wire shell commands to events inside Claude Code — the same way you'd use git hooks or npm lifecycle scripts, but for your AI coding agent.

Every time Claude performs an action (writes a file, runs a Bash command, calls a tool), hooks fire your shell code automatically. You don't change any prompts. You don't ask Claude to remember a rule. The hook runs regardless of what Claude is doing.

Hooks are stored in settings.json — either project-scoped (.claude/settings.json) or user-scoped (~/.claude/settings.json). They're plain JSON, version-controllable, and shareable with your team.

The 4 hook events

Matchers

Each hook is scoped to a tool name pattern via a matcher field. Set it to the exact tool name (Write, Bash, Edit, Read) or use "" (empty string) to match every tool call.

settings.json structure

Here is the complete JSON structure. Add a "hooks" key to either .claude/settings.json (project) or ~/.claude/settings.json (user-global):

Copy{
  "permissions": { ... },

  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/local/bin/check-dangerous-command.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude finished\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Each event key maps to an array of hook groups. Each group has a matcher (tool name or "" for all) and a hooks array. The type is always "command" — it runs the shell command string via bash -c.

Environment variables in hooks

Claude Code injects these into every hook's environment at runtime:

Copy-paste hook patterns

The most useful hooks developers add in the first week. Each is a drop-in hooks value for your settings.json.

1. Auto-format every file Claude writes

Copy"hooks": {
  "PostToolUse": [
    {
      "matcher": "Write",
      "hooks": [
        {
          "type": "command",
          "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\" 2>/dev/null || true"
        }
      ]
    }
  ]
}

2. Lint-on-write with ESLint

Copy"hooks": {
  "PostToolUse": [
    {
      "matcher": "Write",
      "hooks": [{ "type": "command", "command": "npx eslint --fix \"$CLAUDE_TOOL_INPUT_FILE_PATH\" 2>/dev/null || true" }]
    },
    {
      "matcher": "Edit",
      "hooks": [{ "type": "command", "command": "npx eslint --fix \"$CLAUDE_TOOL_INPUT_FILE_PATH\" 2>/dev/null || true" }]
    }
  ]
}

3. Auto-stage files Claude modifies

Copy"hooks": {
  "PostToolUse": [
    {
      "matcher": "Write",
      "hooks": [{ "type": "command", "command": "git add \"$CLAUDE_TOOL_INPUT_FILE_PATH\" 2>/dev/null || true" }]
    }
  ]
}

4. Desktop notification when Claude stops

Copy"hooks": {
  "Stop": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "osascript -e 'display notification \"Claude finished\" with title \"Claude Code\"' 2>/dev/null || notify-send 'Claude Code' 'Claude finished' 2>/dev/null || true"
        }
      ]
    }
  ]
}

5. Log every Bash command Claude runs

Copy"hooks": {
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        {
          "type": "command",
          "command": "echo \"[$(date -u +%FT%TZ)] [$CLAUDE_SESSION_ID] $CLAUDE_TOOL_INPUT_COMMAND\" >> ~/.claude-audit.log"
        }
      ]
    }
  ]
}

6. Slack notification when Claude finishes

Copy"hooks": {
  "Stop": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "curl -s -X POST -H 'Content-type: application/json' --data '{\"text\":\"Claude Code finished a task in session $CLAUDE_SESSION_ID\"}' YOUR_SLACK_WEBHOOK_URL"
        }
      ]
    }
  ]
}

Blocking tool calls with PreToolUse

When a PreToolUse hook exits with a non-zero status, Claude Code blocks the tool call and feeds the hook's stderr back to Claude as a rejection reason. Claude will typically explain the block to you and suggest an alternative.

Example: block writes to production config

Copy"hooks": {
  "PreToolUse": [
    {
      "matcher": "Write",
      "hooks": [
        {
          "type": "command",
          "command": "if echo \"$CLAUDE_TOOL_INPUT_FILE_PATH\" | grep -qE '(prod|production|\.env\.prod)'; then echo 'Writing to production config is blocked by hook policy' >&2; exit 1; fi"
        }
      ]
    }
  ]
}

Example: require tests to pass before any commit

Copy"hooks": {
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        {
          "type": "command",
          "command": "if echo \"$CLAUDE_TOOL_INPUT_COMMAND\" | grep -q 'git commit'; then npm test --silent 2>&1 || { echo 'Tests must pass before committing' >&2; exit 1; }; fi"
        }
      ]
    }
  ]
}

Using /update-config to add hooks without editing JSON

The /update-config skill is the fastest way to add hooks — describe what you want in plain English and Claude writes the correct JSON:

1. Open Claude Code in any project.
2. Type: /update-config
3. Describe the hook — for example:
   "Add a PostToolUse hook that runs prettier on every file Claude writes"
4. Claude reads your current settings.json and patches in the correct hook JSON, handling escaping and matcher syntax for you.

FAQ

More about skills: see the Claude Skills Browser for the full list of slash commands that work alongside hooks.