Hooks

Hooks and subagents solve different problems.

• Hooks run deterministic automation at defined lifecycle events
• Subagents perform focused tasks in isolated context and return summarised results

Use hooks for controls that must run consistently. Use subagents for work that benefits from specialised instructions, tool restrictions, or separated context.

Hooks

Hooks can run when Claude Code starts a session, requests a tool, completes a tool call, sends a notification, starts or stops a subagent, or finishes execution.

Common uses include:

• Block dangerous commands
• Prevent access to protected files
• Run formatting after file changes
• Run validation after edits
• Notify users when input is required
• Log tool usage for auditing
• Require approval for sensitive actions

Hook execution model

1. Event — A lifecycle event occurs, such as a tool request, file edit, notification, or session completion.
2. Match — Claude Code evaluates the configured matcher to determine whether the hook applies.
3. Execute — The configured command, prompt, HTTP request, or agent-based hook runs.
4. Decide — The hook allows, blocks, modifies, records, or responds to the action.

Configure a project hook

Project hooks are configured in:

.claude/settings.json

Example structure:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint"
          }
        ]
      }
    ]
  }
}

What this hook does:

• Runs after Claude uses an Edit or Write tool
• Executes the configured lint command
• Gives Claude a deterministic validation result

Test hooks before sharing

A hook runs automatically when its matching event occurs. Test the hook locally and confirm the command is safe, fast, cross-platform, and suitable for repeated execution.

Inspect configured hooks

Inside Claude Code:

/hooks

Use the hooks interface to inspect configured events and verify that the expected hook is registered. Claude Code supports command, prompt, agent, and other hook handler types, depending on the lifecycle event and configuration.

Hook safety checklist

• Use the narrowest event and matcher
• Avoid destructive commands
• Quote file paths safely
• Validate all hook inputs
• Set reasonable time limits
• Do not expose secrets in logs
• Ensure commands return meaningful exit codes
• Keep frequently triggered hooks lightweight
• Document operating-system assumptions
• Test failure behavior before committing configuration

Next, see Subagents for delegating focused work into isolated context.