Hooks Integration

The agent's hook system lets you run commands automatically in response to events — before or after tool calls, when notifications fire, or when the session starts and stops. While skills define what the agent can do, hooks define what happens around those actions. Together, they create a powerful automation layer where skills handle the creative work and hooks handle the mechanical follow-up.

What Are Hooks?

Hooks are shell commands configured in your agent's settings.json that execute at specific lifecycle points. They run outside of the agent's context window — they are not AI-powered, they are plain shell scripts. This makes them fast, predictable, and deterministic.

The key distinction: skills are invoked by the user and executed by the agent. Hooks are triggered by events and executed by the shell. Skills are creative and adaptive. Hooks are mechanical and consistent.

Hook Types

Agents like Claude Code support several hook trigger points:

• PreToolUse — Runs before a tool call executes. Can inspect and potentially block the call.
• PostToolUse — Runs after a tool call completes. Can react to the result.
• Notification — Runs when the agent sends a notification (e.g., when a long-running task completes).
• Stop — Runs when the agent finishes its turn and stops generating.

Configuring Hooks in settings.json

Hooks are defined in your .claude/settings.json file (or the global ~/.claude/settings.json). Each hook specifies a matcher to determine when it fires and a command to run.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write "$CLAUDE_FILE_PATH""
      },
      {
        "matcher": "Write|Edit",
        "command": "npx eslint --fix "$CLAUDE_FILE_PATH""
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "echo 'Running command: $CLAUDE_TOOL_INPUT'"
      }
    ]
  }
}

In this configuration, every time the agent writes or edits a file, Prettier and ESLint automatically run on that file. The user never has to ask the agent to format or lint — it happens mechanically on every write.

Example: Auto-Format on Save

The most common hook pattern is auto-formatting. When the agent writes or edits any file, you want it formatted according to your project's style guide automatically.

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

The 2>/dev/null || true suffix ensures the hook never fails, even if Prettier does not recognize the file type. A failing PostToolUse hook does not block the tool call (it already completed), but clean error handling prevents confusing output.

Example: Auto-Lint After File Write

Beyond formatting, you can run linters that provide feedback to the agent. If a PostToolUse hook produces output, that output is visible to the agent, so it can react to linting errors.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx eslint "$CLAUDE_FILE_PATH" --format compact 2>&1 | head -20"
      }
    ]
  }
}

When the agent writes a file with a linting issue, the ESLint output flows back into the conversation. The agent sees the warning and can self-correct in the same turn without the user needing to intervene.

PreToolUse Hooks as Safety Guards

PreToolUse hooks run before a tool call executes and can block it by returning a non-zero exit code. This is powerful for enforcing project rules that should never be violated, regardless of what a skill instructs.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "bash -c 'if [[ "$CLAUDE_FILE_PATH" == *.generated.* ]]; then echo "ERROR: Cannot modify generated files. Run the code generator instead."; exit 1; fi'"
      },
      {
        "matcher": "Bash",
        "command": "bash -c 'if echo "$CLAUDE_TOOL_INPUT" | grep -q "rm -rf /"; then echo "ERROR: Dangerous command blocked."; exit 1; fi'"
      }
    ]
  }
}

The first hook prevents the agent from modifying generated files directly. If the agent tries to edit a .generated.ts file, the hook blocks the operation and returns an error message that the agent can read and act on. The second hook blocks obviously dangerous shell commands.

How Hooks Complement Skills

The most effective automation combines skills and hooks. Here are the patterns that work well together:

• Skill creates, hook polishes. A skill writes new code with the right logic and structure. Hooks auto-format and lint the output. The skill does not need formatting instructions.
• Skill acts, hook validates. A skill makes database migration changes. A PostToolUse hook runs the migration validator to catch schema errors immediately.
• Hook guards, skill respects. PreToolUse hooks enforce invariants (no modifying generated files, no direct production DB access). Skills do not need to know about these rules — the hooks enforce them transparently.
• Hook notifies, skill reacts. A Notification hook can send a desktop notification or Slack message when a long-running skill completes its work.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write "$CLAUDE_FILE_PATH" 2>/dev/null || true"
      },
      {
        "matcher": "Write|Edit",
        "command": "bash -c 'if [[ "$CLAUDE_FILE_PATH" == *.test.* ]]; then npx jest "$CLAUDE_FILE_PATH" --no-coverage 2>&1 | tail -5; fi'"
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "command": "osascript -e 'display notification "$CLAUDE_NOTIFICATION" with title "Claude Code"'"
      }
    ]
  }
}

This configuration auto-formats all written files, auto-runs tests when test files are modified, and sends macOS notifications when the agent has something to report. Combined with well-crafted skills, this creates a workflow where the mechanical aspects of development are fully automated.

What's Next

Now that you understand how hooks and skills work together, the next lesson covers visual output — how skills can generate rich HTML output for data visualization, reports, and interactive displays.