What Are Claude Code Hooks? Automate Your Dev Workflow

You tell Claude to build a feature. It does — and it does it well. But then you realize it never ran your tests. Or it didn't format the file. Or you just wish something would happen automatically every time Claude touches your code.

You could keep asking Claude to remember. But Claude is AI — it works off instructions, not habits. Claude Code hooks are the fix for that. They're how you make things happen automatically, every time, without asking twice.

---

The Problem Hooks Are Solving

Claude is smart, but it's not automatic. Every time you want something done — run a linter, check your tests, format a file — you either have to ask for it in your prompt or hope Claude infers that you'd want it.

That works fine until it doesn't. The first time Claude writes a file and your formatter doesn't run, you notice. By the fifth time, it's genuinely annoying. Hooks solve this by moving that responsibility out of the conversation entirely. You define what should happen, and it just happens.

---

What Is a Claude Code Hook?

A hook is a shell command that Claude Code runs automatically when a specific event fires. You configure hooks in your settings file, and from that point on, whenever the matching event happens, your command runs — no matter what you said in the prompt, no matter what Claude decided to do.

That's the key distinction: hooks aren't suggestions. They're deterministic. Claude's judgment isn't involved. If the event fires, the command runs. Period.

---

How Hooks Fit Into Claude Code's Lifecycle

Claude Code works through a cycle: it receives your message, decides what to do, uses one or more tools (read a file, write a file, run a command), and reports back. Hooks plug into specific points in that cycle.

A PreToolUse hook fires before a tool runs — so you can inspect or even block the action. A PostToolUse hook fires after — so you can react to what just happened. Other hooks fire at the session level when Claude stops or a subagent finishes.

The result is that your custom behavior runs as a natural part of Claude's workflow, not something bolted on after the fact.

---

The Five Hook Events

| Event | When it fires | Common use | |---|---|---| | PreToolUse | Before Claude uses any tool | Block writes to sensitive files, log what Claude is about to do | | PostToolUse | After Claude uses any tool | Run a formatter, trigger tests, notify you of changes | | Stop | When the main Claude session ends | Send a desktop notification, log session summary | | SubagentStop | When a subagent finishes | Same as Stop, but scoped to a subagent | | PreCompact | Before Claude compacts the context window | Save a snapshot, log current state |

These are five of the most useful events — Claude Code actually supports many more (like SessionStart, UserPromptSubmit, Notification, and others). You can attach hooks to any or all of these events. You can also filter by tool name using a matcher, so your hook only runs for specific tools — like only triggering after Claude uses the Write tool.

---

What a Hook Actually Looks Like

Hooks live in .claude/settings.json (project-level, commit to your repo) or ~/.claude/settings.json (user-level, applies to all projects) under a "hooks" key. Here's a minimal example that runs a linter every time Claude writes a file:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx eslint --fix \"$CLAUDE_PROJECT_DIR/src\""
          }
        ]
      }
    ]
  }
}

Breaking that down:

• "PostToolUse" — this hook fires after a tool runs
• "matcher": "Write" — only trigger when the tool used was Write (not every tool)
• "command" — the shell command to run

The $CLAUDE_PROJECT_DIR environment variable is set by Claude Code and points to your project root. The file path that was just written is passed to your hook via stdin as JSON — not as an environment variable. Which brings us to how data gets passed in.

---

How Claude Passes Data to Your Hook

When a hook fires, Claude Code sends a JSON payload to your command's stdin. That payload includes context about the event — the tool name, the file path, the arguments Claude passed to the tool, and more.

For a PostToolUse event on the Write tool, the stdin payload looks like:

{
  "session_id": "abc123",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": { "file_path": "/your/project/src/index.js", "content": "..." },
  "tool_response": { "filePath": "/your/project/src/index.js", "success": true }
}

This means your hook scripts can be intelligent. A Python or bash script can read that JSON, check whether the file is in a sensitive directory, and act accordingly. You're not just running a blind command — you have real information to work with.

For simple use cases you don't need to parse stdin at all. For more sophisticated hooks — like one that only formats certain file types — parsing stdin is what makes it possible.

---

Five Things You Can Do With Hooks Right Now

1. Auto-format on file save Set a PostToolUse hook with a Write matcher to run Prettier, Black, or whatever formatter your project uses. Every file Claude writes comes out pre-formatted, without you ever mentioning it.

2. Run tests after edits Add a PostToolUse hook that runs your test suite after Claude writes to a file. You'll know immediately if something broke — before Claude even finishes the session.

3. Block writes to sensitive files Use a PreToolUse hook to check whether Claude is about to write to a .env file or another path you want to protect. If it matches, the hook exits with code 2 to block the write entirely — Claude sees your stderr message as an error and can't proceed. Claude can't override this — it's not AI judgment, it's code.

4. Log Claude's activity Run a simple logging command on every PostToolUse event — append the tool name, file path, and timestamp to a log file. Useful if you want a record of everything Claude touched in a session.

5. Send a desktop notification when Claude finishes Hook into the Stop event to fire a system notification. On Mac you can use osascript, on Windows you can use PowerShell's New-BurntToastNotification or a simple msg command. You'll know Claude is done even if you've tabbed away.

---

How to Add a Hook (Two Ways)

Option 1: Edit settings.json directly

Open .claude/settings.json in your project root (create it if it doesn't exist) and add a "hooks" key following the structure shown above. This gives you full control and works well once you've done it once. If you want hooks to apply to all your projects, use ~/.claude/settings.json instead.

Option 2: Use the /hooks slash command (for inspection)

Inside Claude Code, type /hooks to open a read-only browser showing all your configured hooks — every event, matcher, and handler, with the source file each one comes from. It's useful for checking what's active, but you still need to edit settings.json directly to add or change hooks.

Both project-level (.claude/settings.json) and user-level (~/.claude/settings.json) hooks show up here together.

---

Should You Use Hooks?

Hooks are completely optional. Claude Code works fine without them. But if you've hit the "Claude forgot to do X again" wall more than once, that's the sign to set one up.

A few questions to ask yourself:

• Is there something you always want to happen after Claude writes a file? → PostToolUse hook
• Do you want a notification when Claude finishes a long task? → Stop hook
• Is there a file or directory Claude should never touch? → PreToolUse hook to block it

Start with one. Auto-formatting is the lowest-friction place to begin — set it up once, and you'll immediately feel the difference.

Hooks are not a beginner requirement. But once you've used Claude Code long enough to develop preferences about how your workflow should behave, hooks are the cleanest way to enforce them.

---

Related Features Worth Knowing

If hooks got you curious about customizing how Claude Code behaves, two other features are worth understanding:

Skills are a companion layer to hooks. Where hooks control when things happen automatically, skills control how Claude thinks and responds in a given domain. They work well together — skills shape Claude's output, hooks react to it.

Agents and subagents are relevant if you're using the SubagentStop event. When Claude spins up subagents to handle parallel work, SubagentStop fires each time one of them finishes — useful if you want to react to intermediate results rather than waiting for the whole session to end.

---

If you haven't installed Claude Code yet, start with the guide for Windows or Mac.