Claude Code Hooks Guide 2026: Automate Your Dev Workflow

Hooks turn Claude Code into a fully automated dev assistant - running your formatters, tests, and notifications without you asking.

What are Claude Code Hooks?

The mental model: hooks are like cron jobs, but instead of running on a time schedule, they run on Claude Code events. Anything you can do from the command line, a hook can do - formatters, linters, tests, notifications, logging, file backups.

Hooks matter because they close the gap between "Claude wrote good code" and "the code is actually ready to commit." Without hooks, you rely on remembering to run the formatter, remembering to run the linter, remembering to check for secrets before a commit. With hooks, those steps happen automatically every single time, regardless of whether you or Claude remembers to trigger them manually. For teams running Claude Code across multiple developers, hooks defined in a shared project settings.json also become a way to enforce consistent standards - every developer's Claude session runs the same formatter and the same safety checks, without anyone needing to configure it individually.

All Hook Events Available

How to Set Up Your First Hook

Hooks live in ~/.claude/settings.json (user-level) or .claude/settings.json (per-project). Here is a minimal example that plays a sound every time Claude finishes:

{
  "hooks": {
    "Stop": [
      {
        "type": "command",
        "command": "say 'Claude is done'"
      }
    ]
  }
}

On macOS this will literally speak "Claude is done" out loud. On Windows you might use powershell -c "[console]::beep(800,300)". On Linux: paplay /usr/share/sounds/freedesktop/stereo/complete.oga.

Save the file. The next time Claude finishes a task, the hook fires. No restart needed.

8 Powerful Real-World Examples

1. Auto-format every file Claude edits

"PostToolUse": [
  {
    "matcher": "Edit|Write",
    "type": "command",
    "command": "prettier --write $CLAUDE_FILE_PATH"
  }
]

2. Run tests after every change

"Stop": [
  {"type":"command","command":"npm test"}
]

3. Block dangerous bash commands

"PreToolUse": [
  {
    "matcher": "Bash",
    "type": "command",
    "command": "echo \"$CLAUDE_BASH_COMMAND\" | grep -q 'rm -rf' && exit 1 || exit 0"
  }
]

4. Slack notification when Claude needs you

"Notification": [
  {
    "type":"command",
    "command":"curl -X POST -d 'Claude needs attention' $SLACK_WEBHOOK"
  }
]

5. Log every prompt for auditing

"UserPromptSubmit": [
  {"type":"command","command":"echo \"$(date): $CLAUDE_USER_PROMPT\" >> ~/claude-log.txt"}
]

6. Auto-commit completed work

"Stop": [
  {"type":"command","command":"git add -A && git commit -m 'WIP: Claude session' --no-verify"}
]

7. Backup files before any edit

"PreToolUse": [
  {"matcher":"Edit","type":"command","command":"cp $CLAUDE_FILE_PATH $CLAUDE_FILE_PATH.bak"}
]

8. Desktop notification on completion

"Stop": [
  {"type":"command","command":"osascript -e 'display notification \"Done\" with title \"Claude\"'"}
]

A small settings.json change can turn Claude Code into a fully automated dev assistant.

Hooks vs Skills vs Subagents

Claude Code has three distinct automation and extension mechanisms, and it is easy to reach for the wrong one. Hooks, Skills, and Subagents solve different problems, and understanding the boundary between them saves a lot of trial and error.

A useful rule of thumb: if the action should happen the exact same way every time with zero judgment involved, that is a hook. If it needs Claude's reasoning to decide how to apply a set of guidelines, that is a Skill. If it is a self-contained chunk of work that benefits from its own fresh context, that is a Subagent. Many production Claude Code setups use all three together - Skills to guide how Claude approaches a task, Subagents to parallelize pieces of it, and Hooks to guarantee the boring, repetitive safety and quality steps never get skipped.

Debugging Hooks That Don't Fire

The most common hook problem is silence - you add a hook, nothing happens, and there's no obvious error message. Work through these checks in order:

• Check the JSON is valid. A single missing comma in settings.json silently breaks the entire hooks block. Run the file through a JSON validator before assuming the hook logic itself is wrong.
• Confirm the matcher pattern. "matcher": "Edit" only fires for the Edit tool - if Claude used Write instead, the hook never triggers. Use "Edit|Write" to cover both.
• Check file scope - project vs user settings. A hook in .claude/settings.json only applies within that project directory. If you're testing from a different folder, it won't fire.
• Redirect output to a log file while testing. Append > /tmp/hook-debug.log 2>&1 to the command so you can see exactly what ran and what error, if any, it produced.
• Verify the command works standalone first. Copy the exact command out of settings.json and run it directly in your terminal. If it fails there, the hook was never going to work either.

Safety & Best Practices

1. Test on a sandbox project first. A bad PreToolUse hook can lock you out of using Claude. Test on a throwaway repo before adding to your main project.
2. Keep hook commands simple. One-line shell commands are easy to debug. Big bash scripts hidden inside JSON are not.
3. Use matchers to limit scope. matcher: "Edit|Write" means the hook only fires for those tools - not every single tool.
4. Log hook outputs while developing. Add > /tmp/hook.log 2>&1 at the end of new hooks until you trust them.
5. Never bypass safety. Hooks should add automation, not skip Claude's permission prompts. Wrapping --no-verify into a hook is asking for trouble.

One practical habit worth building early: start every new project with just two hooks - a PostToolUse formatter and a Stop-event test runner - before adding anything more elaborate. Teams that try to configure a dozen hooks on day one usually end up debugging JSON syntax errors instead of shipping code. Add hooks incrementally as you notice a repeated manual step, and each one will earn its place rather than becoming unused configuration nobody remembers the purpose of six months later.

For more Claude developer context, see our guides on Claude Skills Feature and Claude Agent SDK Guide. If your team needs this kind of automation built around your own tools and CRM, see our AI agent automation services.

Looking for the best information about Claude Code hooks? Quick takeaway: add 2 hooks today. Start with PostToolUse for auto-formatting and Stop for desktop notifications. From there, you will discover more automations naturally. Hooks are the most underused power feature in Claude Code.

Written by Mayank Kumar Prajapati

Founder, Mayank Digital Labs

7+ years building AI automation and digital marketing systems for businesses across India and 12+ countries. I write about AI tooling, SEO, and growth strategy I've personally tested with real clients.

LinkedIn · About · Get in touch