Claude Code Hooks: How to Automate Your Workflow in 2026

Claude Code hooks are the feature that turns Claude Code from a smart coding assistant into something you can actually shape.

If skills tell Claude how to think about a workflow, hooks tell Claude Code when something must happen. That difference matters. A skill is guidance. A hook is enforcement. If you want automatic formatting, guardrails around dangerous commands, desktop notifications, config auditing, or context injection after compaction, hooks are the right tool.

That is why this keyword is worth covering now. Anthropic’s hooks docs have expanded, more example repos have shown up in the last few weeks, and developers are starting to realize hooks solve a class of workflow problems that prompts alone do not.

What Claude Code hooks actually are

Claude Code hooks are user-defined commands, HTTP endpoints, or prompt-based handlers that run at specific points in Claude Code’s lifecycle.

Anthropic’s docs describe them as deterministic control over Claude Code behavior. That is the key idea. You are not hoping the model remembers to lint a file, block a risky edit, or notify you when it finishes. You are wiring that behavior into the runtime.

This is the simplest mental model:

• Skills add reusable instructions and workflows
• MCP servers add tools Claude can call
• Hooks run automatically when lifecycle events fire

If you already read the Claude Code skills guide, this is the missing second half. Skills package judgment. Hooks package automation.

Why Claude Code hooks matter right now

Hooks matter because Claude Code is getting used for longer-running and more autonomous work.

Once you move past toy prompts, the pain points show up fast:

• you want formatting to happen every time, not most of the time
• you want to block destructive shell commands before they run
• you want a clean audit trail when settings change
• you want context restored after compaction
• you want Claude to ping you when it finishes instead of babysitting the terminal

That is exactly the gap hooks fill.

They also create a real moat versus lighter AI coding tools. Plenty of editors can autocomplete or apply an edit. Fewer let you attach event-driven workflow logic to the agent loop itself. That is why hooks are showing up more often in serious Claude Code setups, team workflow posts, and GitHub example repos.

The hook events most developers actually need

Anthropic documents a long list of lifecycle events, but most developers do not need all of them on day one.

The ones worth caring about first are:

• Notification for “Claude needs your input”
• PreToolUse to inspect or block a tool call before it runs
• PostToolUse to run something after an edit or write succeeds
• PermissionRequest to inspect approval prompts
• Stop for end-of-task automation
• SessionStart for startup context injection
• ConfigChange to track settings or skills changes
• PreCompact and PostCompact for long sessions

That list covers most of the practical wins.

If your main use case is project rules, start with PreToolUse. If your problem is workflow polish, start with PostToolUse and Notification. If your sessions run long, care about SessionStart, PreCompact, and PostCompact sooner than you think.

Where Claude Code hooks live

Claude Code supports multiple settings locations:

• ~/.claude/settings.json for hooks you want everywhere
• .claude/settings.json for project hooks worth committing
• .claude/settings.local.json for local project hooks you do not want in git

The rule is simple.

Put personal workflow preferences in your user settings. Put team-safe automation in the project settings file. Keep machine-specific or noisy experiments in the local settings file.

That mirrors how you should think about OpenClaw skills and Claude skills in general: share what belongs to the project, keep private ergonomics private.

Your first Claude Code hook

The easiest useful hook is a notification when Claude is waiting for you.

Add this to ~/.claude/settings.json on macOS:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

This is a tiny example, but it proves the pattern.

A hook event fires. Claude Code passes context into your handler. Your command runs automatically. You get deterministic behavior instead of hoping the model does the right thing.

Once that clicks, the rest of the feature makes sense.

Claude Code hooks tutorial: 5 production patterns worth stealing

Here are the five patterns I think are actually worth implementing.

1. Auto-format files after Claude edits them

If Claude edits JavaScript, TypeScript, Markdown, or JSON in your repo, formatting should not depend on memory.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

This pattern is great because it removes low-value churn from reviews. Claude edits the file, Prettier cleans it up, and you stop wasting cycles on whitespace noise.

One warning: only do this when your formatter is fast and stable. If your post-edit command is slow, you will feel it immediately.

2. Block edits to protected files

This is the hook most teams should add early.

You probably do not want an agent editing .env, lockfiles, generated migration artifacts, or random files under .git/ unless you asked for it explicitly.

A PreToolUse hook lets you block those writes before they happen. Anthropic’s docs show the pattern with a shell script that reads JSON from stdin, checks the target path, and exits with a blocking decision when it matches a protected pattern.

That is much better than cleaning up after a bad edit.

If you are building production agents or doing client work, this is one of the easiest ways to make agentic coding safer without killing speed. It also fits the same trust-boundary logic I talked about in the OpenClaw security guide: automate guardrails around risky capabilities instead of relying on vibes.

3. Block destructive shell commands

The other obvious PreToolUse pattern is shell command filtering.

For example, you can inspect Bash input and deny commands containing things like:

• rm -rf
• force pushes to protected branches
• direct writes into production config paths
• ad hoc secret exfiltration commands

The official hooks reference shows this with a script that reads .tool_input.command, checks for a banned pattern, and returns a denial decision.

This is not a replacement for sane permissions. It is defense in depth.

If Claude has Bash access, you want both:

1. permission controls
2. hooks that catch obviously bad commands

4. Re-inject important context after compaction

Long Claude Code sessions eventually compact. That is necessary, but it can drop details you care about.

Hooks give you a clean workaround.

Anthropic’s docs show a SessionStart hook with a compact matcher that prints a reminder back into context after compaction. That reminder might include:

• which package manager to use
• current sprint focus
• architecture constraints
• commands that must run before commit

Example:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use pnpm, not npm. Run pnpm test before commit. Current focus: billing retry bugs.'"
          }
        ]
      }
    ]
  }
}

This is one of those boring features that becomes very valuable once you start doing multi-hour sessions.

5. Create completion notifications or checkpoints

The Stop hook is perfect for end-of-task workflow automation.

At the simple end, use it for desktop notifications.

At the more interesting end, use it for checkpointing. GitButler wrote about using Claude Code hooks to create save points and organize agent work more cleanly. You do not need their whole stack to copy the underlying idea: when the session ends, run a small automation that leaves the repo in a more traceable state.

That could mean:

• a notification
• a local log entry
• a transcript archive
• a lightweight git checkpoint in an experimental branch

Be careful with automatic commits to shared branches. The idea is good. The default implementation can be bad if you overdo it.

Common mistakes with Claude Code hooks

Most hook problems come from one of four mistakes.

Writing giant shell one-liners

Start with a shell script file when logic gets even a little complicated. It is easier to debug, review, and share.

Putting team-specific automation in user settings

If the whole team should benefit from the automation, commit it in .claude/settings.json. If it is only for your machine, keep it in ~/.claude/settings.json or .claude/settings.local.json.

Using hooks where a skill is better

Hooks are event-driven and good for deterministic behavior. They are not the right place for large reusable instructions or domain knowledge. That belongs in a skill.

A useful shortcut:

• if the problem starts with when this happens, run X, use a hook
• if the problem starts with when working on Y, follow this process, use a skill

Forgetting performance costs

Every hook adds latency somewhere. One fast notification hook is cheap. A chain of slow post-edit commands is not.

Keep the high-frequency hooks small. Heavy work belongs in a background process, an agent, or a tool designed for it.

Should you use Claude Code hooks or just keep everything in prompts?

Use prompts for preferences. Use hooks for guarantees.

That is the cleanest way to think about it.

A prompt can tell Claude, “please run tests before finishing.” A hook can actually enforce a check at the right moment. A prompt can say, “avoid editing secrets.” A hook can block writes to .env outright.

Once you care about repeatability, hooks win.

That is also why hooks pair so well with the rest of the modern agent stack. Skills package workflows. MCP expands tool access. Hooks keep the workflow honest. If you want the broader architecture around tool surfaces and agent extensions, read the MCP server tutorial.

The practical takeaway

Claude Code hooks are not flashy, but they are one of the highest-leverage features in the product.

They let you take the parts of your workflow that should be automatic, safe, and repeatable, and move them out of wishful prompting into actual runtime behavior.

If you only implement three hooks this week, make them these:

1. Notification so you can stop babysitting the terminal
2. PreToolUse to protect sensitive files and risky shell commands
3. PostToolUse to auto-format edited files

That gets you most of the value fast.

After that, add compaction recovery and audit logging. That is where Claude Code starts feeling less like a chatbot in your terminal and more like an agent you can trust to work inside real developer constraints.