Hooks

Hooks let Claude Code trigger project automation around important events. Start with observability and lightweight checks before adding blocking policy.

Useful Hook Categories

• Pre-action checks for risky shell commands.
• Post-edit formatting or targeted linting.
• Session summary capture before compaction.
• Directory change notifications for workspace-specific rules.
• Permission denial logging so teams can improve allowlists.

Design Rules

Hooks should be fast, deterministic, and easy to bypass only through an explicit policy decision. They should not surprise the developer with long-running work.

Good hook behavior:

• Emits a clear message.
• Names the command it ran.
• Fails with an actionable reason.
• Stays scoped to the changed area.

Bad hook behavior:

• Installs packages.
• Mutates unrelated files.
• Runs the entire CI suite on every small edit.
• Hides the reason a command was blocked.

Example Policy

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "yarn workspace handbook typecheck"
          }
        ]
      }
    ]
  }
}

Use this shape only when the command is fast enough for the repository. For large projects, prefer focused scripts that inspect changed files first.

Rollout Pattern

1. Log the event without blocking.
2. Add a warning for known risky patterns.
3. Block only the commands or states that have caused real damage.
4. Document the hook in onboarding material.
5. Review false positives after every week of use.