Try free

Last updated 13 October 2026

How to add custom hooks to Claude Code

Automated workflows with hooks

Your terminal workflow breaks when you have to manually trigger tests or deployments after every change. You want Claude Code to finish a task and immediately run a shell script without your intervention. Hooks allow you to bridge the gap between the agent and your local environment. They listen for specific events in the lifecycle of a session and execute commands you define. This automation keeps your hands off the keyboard while the agent handles repetitive chores like linting or building.

Setting up these triggers keeps you in the flow of coding rather than managing the agent. You can automate the boring parts like running a specific test suite or sending a notification to your system tray. This prevents the agent from idling while you wait for it to realize a job is done. By using hooks, you ensure that the agent follows your specific project protocols every time it touches the codebase. It makes the agent a more integrated part of your development pipeline.

Configuring events in settings files

You control hook behavior through the .claude/settings.json file in your project root or the global version in your home directory. The configuration structure maps specific hook events to the shell commands you want to run. If you want a hook to apply only to your current project, use the local project file. Use the global file at ~/.claude/settings.json if you want a notification script to run across every repository you manage on your machine.

The system supports several events such as PostToolUse and Stop. For most automation, the Stop event is the most useful because it triggers when the agent finishes its current objective. You define the hook by adding a hooks object to your JSON settings. Inside this object, you list the event name and provide the path to your executable script or a direct bash command. The agent reads this file every time a session starts, so your changes take effect the next time you run the claude command.

Automating test suites after edits

A common pattern is running a build or a test suite every time the agent modifies your code. You can use the PostToolUse event to trigger a script specifically after the Edit or Write tools are finished. This ensures that the agent receives immediate feedback if its changes break the compilation. It forces the agent to see the error in the terminal output before it moves on to the next task. This loop helps the agent self-correct without you having to point out the syntax errors manually.

In your .claude/settings.json file, you specify the bash command under the PostToolUse event. You might point it to a shell script that runs your package manager test command. If the script fails, the output appears in the session history just like any other bash output. The agent can then use its Bash tool to read the logs and fix the bugs it just introduced. This creates a highly autonomous environment where the agent manages its own quality control.

Monitoring long running tasks with notifications

When you give the agent a complex refactoring task, you might switch to another window to handle email or other work. You do not want to keep checking the terminal to see if it finished. The Notification hook is designed for this scenario. You can hook this event into a system notification tool to get a desktop alert when the agent requires your attention. This keeps you productive on other tasks while the agent works in the background.

This hook sends data about the current state of the session to your script. You can write a small Python or Shell wrapper that parses the event message. If the agent hits a permission prompt or completes the entire task, the script triggers the alert. This allows you to walk away from your desk and know exactly when the agent is ready for your review. It turns the agent into a background process that calls you only when it truly needs a human decision.

Managing multiple sessions with adhdTerminal

If you run several Claude Code sessions at once, managing individual hooks manually becomes a chore. This is where adhdTerminal becomes a significant asset for your workflow. It allows you to see the status of every session on a single wall of tiles. Each tile clearly shows whether a session is working, waiting for you, or done. This visual feedback complements your custom hooks by giving you a high-level view of your entire project landscape.

While your hooks run scripts in the background, adhdTerminal provides the visibility you need to stay organized. You can see the last exchanges of a conversation in a tile without switching terminal tabs. If a hook triggers a build failure, the tile updates to show the idle or error state. This combination of background automation through hooks and foreground visibility through the adhdTerminal wall helps you maintain focus on the high level project goals instead of getting lost in terminal management.

Cleaning up context with pre-compact hooks

The PreCompact hook is useful for managing the context window of a long session. When a session gets too large, the agent might suggest running /compact to summarize the history and free up space. You can use the PreCompact hook to archive the current state of the conversation before the summary happens. This ensures you have a record of the detailed conversation before the agent compresses it into a shorter summary.

To implement this, you add the hook to your settings and point it to a logging script. The script can copy the current session log or the contents of your project instructions from CLAUDE.md into a timestamped folder. This gives you a safety net. If the summarization loses a specific detail you needed, you can find it in your local archives. It makes the /compact command much safer to use during long development sessions.

Initializing environments on session start

The SessionStart event allows you to prepare your environment every time you run the claude command. You can use this hook to check for updates using claude update or to verify your current login status with /status. It is also a good place to run a script that cleans up temporary build artifacts or resets a local database to a known state. This ensures that the agent always begins its work in a predictable environment.

This automation removes the need to remember your setup scripts manually. By putting these commands in the SessionStart hook, you automate the preparation phase of your development cycle. The agent begins its work in an environment that is already configured exactly how you need it. It reduces the chance of errors caused by stale build files or incorrect environment variables that were left over from a previous session.

Using subagent hooks for complex pipelines

When you use subagents via markdown files in .claude/agents, you can monitor their progress with SubagentStop. This is different from the main session stop event. It allows you to trigger specific logic when a specialized sub-task finishes. For example, if a subagent is responsible for generating documentation, you can use this hook to automatically commit those changes to a specific branch as soon as the subagent exits.

This creates a chain of automation where the main agent starts a subagent, the subagent finishes its work, and your hook immediately processes the output. You define these hooks in the same .claude/settings.json file. By separating the hooks for the main agent and subagents, you can create more granular and efficient workflows. This prevents the system from firing unnecessary scripts during simple interactions that do not involve sub-tasks.

Troubleshooting and testing your hooks

If a hook does not seem to fire, use the /doctor command to check the health of your installation. Ensure that the scripts you are calling have the correct execution permissions on your filesystem. You can test your hook logic by running a simple prompt with claude -p to see if the event triggers as expected. If the hook produces an error, it will usually be reported in the terminal output of the session, allowing you to debug the bash script directly.

Check your .claude/settings.json for syntax errors like missing commas or quotes. The agent respects these settings strictly and will ignore the hooks if the JSON is malformed. If you find that hooks are firing too often, consider moving them from PostToolUse to Stop. This reduces the frequency of execution and ensures the script only runs when the agent has completed a logical block of work rather than after every single file read or directory search.

Questions people ask

How do I pass session data to my hook script?

Claude Code passes event details as environment variables to your script when a hook triggers. You can access variables like the session ID or the specific event type within your shell script. This allows you to log specific data or filter actions based on the context of the event.

Can I disable hooks for a single session?

You can override your hook settings by using a .claude/settings.local.json file in your project. If you need a session without automation, you can temporarily modify this file to have an empty hooks object. There is currently no command line flag to skip hooks during the initial launch.

Do hooks run when using bypassPermissions mode?

Yes, hooks execute regardless of the current permission mode you are using. If you are in bypassPermissions mode, the agent will run its tools without asking, and then the hooks will trigger immediately after. The hook script runs as a local process with your standard user permissions.

Read next

More on claude code basics·All posts