Claude Code Hooks Examples: Guardrails That Always Run

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "node \"${CLAUDE_PROJECT_DIR:-.}/scripts/review-blog-figures.mjs\" --hook 2>/dev/null || true",
            "timeout": 30,
            "statusMessage": "Checking whether the figures fit"
          }
        ]
      }
    ]
  }
}

This repo's entire shared hook config. The exact matcher Write|Edit runs the figure review after every Write or Edit and never for Bash. It uses shell form rather than exec form because it needs the shell's 2>/dev/null || true, and it wraps the path placeholder in double quotes, as the docs ask for shell form. timeout: 30 replaces the 600-second default; statusMessage is the text in the spinner while it runs.

if (HOOK_MODE) {
  let file = "";
  try {
    const payload = JSON.parse((await readStdin()) || "{}");
    file =
      payload.tool_input?.file_path ?? payload.tool_response?.filePath ?? "";
  } catch {
    process.exit(0); // Not our payload; a hook must never break the edit.
  }
  const component = WATCHED.component.exec(file);
  if (component) only = component[1];
  checkPixels = WATCHED.registry.test(file) || WATCHED.inline.test(file);
  // Editing anything else — a page, a script, a message file for a post we
  // cannot identify — is not a figure change worth a report.
  if (!component && !checkPixels && !WATCHED.messages.test(file))
    process.exit(0);
}

The input side. It parses the payload from stdin and takes tool_input.file_path, falling back to tool_response.filePath. A payload it can't parse, or a file that isn't a blog component, the figure registry, an inline image or a message file, exits 0 at once, so most edits cost one Node start and nothing else.

    const shown = ordered.slice(0, HOOK_MAX_FINDINGS);
    const omitted = ordered.length - shown.length;
    const lines = shown.map(
      (f) => `- ${f.component} [${f.check}] ${f.message}`,
    );
    if (omitted)
      lines.push(
        `- …and ${omitted} more not listed here (run the script for all)`,
      );
    process.stdout.write(
      JSON.stringify({
        hookSpecificOutput: {
          hookEventName: "PostToolUse",
          additionalContext:
            `Figure-fitness review (${scope}) — ADVISORY, nothing is broken:\n${lines.join("\n")}\n` +
            `Look at each image before deciding: does its subject match the section's subject? ` +
            `If the post is about experience or methodology, draw a diagram (scripts/generate-blog-diagram.mjs) ` +
            `instead of borrowing a photograph. Run node scripts/review-blog-figures.mjs for the full report.`,
        },
      }),
    );
  }
  process.exit(0);

The answer side. One JSON object with hookSpecificOutput, hookEventName and additionalContext, and always exit 0. Findings are capped at HOOK_MAX_FINDINGS, which is 12, so a noisy check can't flood the context it is advising, and the text opens by stating plainly that it is advisory. With no findings it prints nothing at all.