Claude Code Hooks: Events, Examples, and Safe Setup Patterns

Feature Comparison

When To Use Hooks

Hooks are useful for recurring validation, formatting checks, lightweight notifications, permission alerts, protected-file guardrails, or team-specific workflow policy.

Safe Pattern

Keep each hook focused on one observable job. Prefer commands that read input, print a clear result, and can be run manually by a developer.

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

Matcher Checklist

A good matcher makes the hook predictable. Match edit tools for lint checks, read/search tools for secret-file guards, PermissionRequest for attention notifications, and Stop for end-of-turn status.

• Start narrow, then expand only after the hook proves useful.
• Document what stdin payload the command expects.
• Use timeouts so hooks cannot stall a session indefinitely.
• Make failure output tell the developer exactly what to do next.

Common Mistakes

Hidden side effects make AI workflows harder to trust.

• Avoid commands that unexpectedly change files.
• Keep deployments, network writes, and credential rotation out of automatic hooks.
• Do not run long full-suite checks after every tool call.
• Document hook behavior in CLAUDE.md or AGENTS.md.

Hook Design Principles

Claude Code hooks should make recurring validation easier to trust. The safest hooks are boring, visible, and easy to run manually when something fails.

• Keep each hook focused on one job such as linting, formatting, or a targeted test.
• Print clear failure output so a developer can reproduce the problem outside the hook.
• Avoid network calls, deployments, or destructive file changes in automatic hooks.
• Document where the hook is configured and which command it runs.

Good Hook Candidates

The best candidates are checks that developers already expect to run before handoff. Hooks should reinforce the normal workflow rather than create a hidden second workflow.

npm run lint
npm test -- --runInBand
npm run typecheck
npm run format:check

Rollout Checklist

Introduce hooks gradually. Start with warnings or fast checks, measure whether they reduce review friction, and only then add broader validation.

• Start with one fast check that finishes consistently.
• Explain the hook behavior in CLAUDE.md or AGENTS.md.
• Give developers a manual command for reproducing failures.
• Review hook scope after the project adds new packages or test suites.

FAQ