Claude Code Hooks: Automate Your Dev Workflow

Why Your AI Coding Agent Needs Guardrails

Claude Code has become the default AI coding companion for a rapidly growing number of developers. But there is a fundamental tension at the heart of any LLM-powered tool: you are handing significant autonomy to a system that operates on probabilities, not certainties. You can write the most detailed CLAUDE.md instructions imaginable, and Claude will follow them most of the time. Most of the time is not good enough when the stakes involve committing secrets to a public repository, pushing unformatted code to main, or skipping your test suite before a deploy.

That is precisely the problem Claude Code hooks solve. Hooks are user-defined commands that execute at deterministic points in Claude Code's lifecycle. They do not rely on the model deciding to follow a suggestion. They run every single time, without exception. Think of them as the difference between asking a colleague to please remember to run the linter and wiring the linter into a pre-commit gate that physically prevents bad code from passing through.

Searches for Claude Code hooks surged over 400 percent in Q2 2026, and for good reason. As Claude takes on more autonomous coding work — Anthropic recently disclosed that Claude now authors more than 80 percent of the code merged into its own codebase — the need for deterministic enforcement has never been higher. This guide covers everything you need to know to set up, configure, and get real value from hooks in your daily workflow.

How Hooks Work Under the Hood

Every action Claude Code performs follows a lifecycle. When Claude edits a file, runs a shell command, creates a commit, or finishes a task, it passes through defined stages. Hooks let you attach your own logic to these stages.

The basic mental model is straightforward. You define a hook in your settings file, specify which lifecycle event triggers it, and provide the command or action to execute. When that event fires, your hook runs. Depending on the event type and exit code, the hook can allow the action to proceed, block it entirely, or modify the context before Claude continues.

Hooks are configured in your settings file, either at the project level in your repository's .claude/settings.json — which gets committed to Git and shared with your team — or at the personal level in your home directory's .claude/settings.json, which applies across all your projects. This two-tier system is powerful: your team enforces shared standards through project hooks, and you layer on personal preferences and security guardrails through user hooks.

The Lifecycle Events That Matter Most

Claude Code exposes a rich set of lifecycle events, and the list has grown substantially in 2026. The full catalog now includes over two dozen events, from SessionStart and Setup through PreToolUse, PostToolUse, Stop, Notification, and newer additions like SubagentStart, SubagentStop, WorktreeCreate, and PreCompact. You do not need to use all of them. Most developers get enormous value from just a handful.

PreToolUse fires before Claude executes any tool — editing a file, running a bash command, creating a commit. This is your gatekeeper. If your hook exits with code 2, the action is blocked and Claude receives your error message so it can course-correct. This is where you put secret scanning, dangerous command blocking, and permission enforcement.

PostToolUse fires after a tool completes successfully. This is where formatting, linting, and validation live. Claude just edited a file? Your PostToolUse hook runs Prettier and ESLint on it before anything else happens. The code never exists in an unformatted state in your working tree.

Stop fires when Claude finishes its turn and is about to hand control back to you. This is ideal for running your full test suite, generating a summary of changes, or triggering a notification that work is done.

Notification fires when Claude needs your input or has completed a background task. With the July 2026 update to Claude Code v2.1.198, this event now fires for background sessions too, so you get notified when a subagent finishes work in a separate worktree.

SessionStart fires when a new Claude Code session begins. Use it to inject context — pull the latest from your branch, check for stale dependencies, or load project-specific environment variables.

The Five Hooks Every Developer Should Set Up

You could spend hours building an elaborate hook system, but the highest-impact hooks are surprisingly simple. Here are the five that deliver the most value with the least setup effort.

Auto-Format on Every Edit

The single most impactful hook for code quality is automatic formatting on every file Claude touches. Configure a PostToolUse hook that triggers on file edit events and runs your project's formatter — Prettier, Black, gofmt, rustfmt, whatever your stack uses — on the changed file. Claude receives the formatted output, so its subsequent edits build on properly formatted code rather than accumulating style drift over a long session.

This matters more than it might seem. In extended coding sessions where Claude makes dozens of edits across multiple files, style inconsistencies compound. A formatting hook eliminates that entire category of cleanup work.

Block Secrets Before They Hit Git

This hook is non-negotiable. Configure a PreToolUse hook that intercepts git commit operations and scans staged files for patterns that look like API keys, tokens, passwords, and environment variables. If anything suspicious is detected, exit with code 2 to block the commit. Claude gets the error message explaining what was found and where.

Accidentally committing credentials to a repository remains one of the most common and damaging mistakes in software development. When an AI agent is writing and committing code autonomously, the risk multiplies. This hook makes it structurally impossible for secrets to enter your git history through Claude, regardless of what the model decides to do.

Lint on Every File Change

Similar to formatting but focused on catching actual errors and anti-patterns. A PostToolUse hook that runs your linter on every file Claude modifies catches issues at the moment they are introduced. Claude sees the lint errors immediately and can fix them in the same session, rather than leaving you with a pile of warnings to clean up later.

For JavaScript and TypeScript projects, running ESLint with your project configuration catches everything from unused variables to accessibility issues. For Python, running Ruff or Flake8 serves the same purpose. The key is that the hook runs your exact project configuration, enforcing the same rules your CI pipeline would catch — just much earlier in the process.

Run Tests Before Committing

A PreToolUse hook on git commit that runs your relevant test suite is the last line of defense before code enters your history. The scope matters here. Running your entire test suite on every commit might be too slow for a smooth workflow, so configure the hook to run only the tests related to the files that changed. Most test runners support this — Jest has its related tests mode, pytest can filter by changed files, and Go tests can target specific packages.

Keep this hook fast. If it takes more than a few seconds for typical changes, developers — and Claude — will feel the friction. Save comprehensive test runs for your pre-push hook or CI pipeline.

Desktop Notifications When Claude Finishes

This one is about workflow, not code quality. Configure a Notification hook that sends a desktop notification whenever Claude finishes a task or needs your input. This lets you context-switch to other work while Claude handles a long coding session without constantly checking back in the terminal. With the latest Claude Code updates supporting background subagents, this becomes even more valuable — you get notified when work completes in worktrees you are not actively watching.

Hook Types Beyond Shell Commands

Most developers start with command-type hooks that run shell scripts, but Claude Code supports several other hook types that open up more sophisticated workflows.

HTTP hooks POST the event data to a URL. This is useful for integrating with external services — sending a Slack message when a session ends, logging all file changes to an audit system, or triggering a CI pipeline when Claude pushes code.

MCP tool hooks call a tool on an already-connected MCP server. If you have MCP servers set up for your project management tool, database, or deployment system, you can trigger actions on those systems directly from hook events.

Prompt hooks run a single-turn LLM evaluation. This is useful for dynamic checks that are hard to express as shell scripts — for example, having an LLM review whether a commit message follows your team's conventions.

Agent hooks are the most powerful type. They spin up a multi-turn agent with tool access to perform complex verification. Use these sparingly, as they are slower, but they are invaluable for things like reviewing whether an architectural change is consistent with your project's design patterns.

Project Hooks vs. Personal Hooks

The two-tier configuration system deserves deliberate thought. Project hooks live in your repository and are shared with everyone on the team. Personal hooks live in your home directory and apply to everything you work on.

Project hooks should encode your team's standards: the specific linter configuration, the test runner command, the commit message format, the branch naming convention. These are rules everyone agrees on and should be enforced uniformly.

Personal hooks should handle your individual preferences and universal safety measures. Secret scanning belongs in personal hooks because you want it on every project, not just the ones that remembered to configure it. Notification preferences are personal. Custom formatting for languages you work with across multiple projects goes here too.

When both project and personal hooks exist for the same event, both run. Personal hooks execute first, then project hooks. If either blocks the action, it is blocked. This means your personal security hooks always have the final say, even if a project does not configure its own.

Common Mistakes to Avoid

The most frequent mistake is making hooks too slow. A PostToolUse hook that takes ten seconds to run will fire on every single file edit. Over a session with fifty edits, that adds over eight minutes of waiting. Keep per-edit hooks under one or two seconds. Save heavier operations for Stop or pre-commit events.

Another common pitfall is hooks that are too noisy. If your hook outputs warnings on every run, Claude starts treating the output as background noise and may not react meaningfully to genuine issues. Keep hook output clean and only surface actual problems.

Do not duplicate what your CI pipeline already does. Hooks should catch issues early and fast, not replicate your entire build process. If a check takes more than a few seconds and does not need to run on every edit, it belongs in CI.

Finally, test your hooks in a scratch project before deploying them to a real codebase. A misconfigured PreToolUse hook that always exits with code 2 will block Claude from doing anything at all, which is a frustrating experience to debug in the middle of actual work.

Getting Started Today

If you have never used hooks before, start with just one: the auto-format hook. Pick whichever formatter your project already uses, set it up as a PostToolUse hook on file edit events, and work with Claude for a day. You will immediately notice that the code Claude produces stays cleaner throughout the session.

Once you are comfortable with that, add secret scanning as a PreToolUse hook on git commits. Then layer on linting. Build up gradually rather than trying to configure everything at once.

The Claude Code documentation at code.claude.com has the full reference for all lifecycle events, hook types, and configuration options. The community has also published collections of ready-to-use hook configurations that you can drop into your settings file and customize.

As Claude Code continues to take on more autonomous work — from background subagents to multi-worktree sessions — hooks become your primary mechanism for maintaining control and quality. They are the bridge between trusting your AI agent to do good work and verifying that it actually did.

If you are tracking how much of your Claude usage goes toward coding versus other tasks, tools like Gaugr can help you monitor your consumption across models and stay on top of your limits in real time.