Last updated 13 October 2026
Run a shell script using Claude Code hooks
Integrate shell automation with agent workflows
You often find yourself running the same sequence of commands after Claude Code makes a change to your files. Whether you need to restart a local development server, run a suite of unit tests, or trigger a build process, these manual steps interrupt your concentration. Every time the agent finishes an Edit or Write task, you have to switch back to your terminal and type out the next shell command. This creates a friction point that slows down the speed of your development cycle and introduces the risk of forgetting a critical validation step before you commit your work.
Shell hooks provide a way to bridge the gap between the agent's actions and your local environment's requirements. By defining specific triggers, you can instruct the CLI to execute your own bash or PowerShell scripts automatically at various points in its lifecycle. This means you can have a linter run immediately after every file change or a cleanup script run when you exit the session. You no longer need to babysit the terminal to ensure your project remains in a valid state while the agent performs complex refactoring or feature implementation tasks.
Configure hook events in the project settings
To start using hooks, you must edit the .claude/settings.json file in your project root or create it if it does not exist. This file uses a standard JSON format where you define a hooks object. Within this object, you map specific event names to the shell commands you want to run. For example, if you want to run a script named verify.sh every time a session concludes, you would associate that script with the SessionEnd event. The CLI looks for these definitions every time it starts or reaches a relevant execution point.
The system supports several distinct events that allow for fine-grained control over your automation. Use SessionStart to prepare your environment, such as by pulling the latest changes from a remote repository or clearing out temporary build artifacts. Use UserPromptSubmit to trigger a script every time you send a new instruction to the agent. If you want to customize how the agent behaves across all your projects, you can place these same hook definitions in your ~/.claude/settings.json file. This global configuration ensures that your essential scripts run regardless of which repository you are currently working in.
Automate testing and linting after file edits
One of the most effective ways to use hooks is through the PostToolUse event. This event triggers after the agent successfully completes a tool action, such as using the Edit or Write tools to modify your source code. By linking this hook to your project linter or a subset of fast-running tests, you can get immediate feedback on the changes the agent just made. If a change breaks the syntax or violates your project's coding standards, your script will run and provide you with the output before the agent moves on to the next task.
This automated feedback loop is particularly useful when you are working on large scale refactoring. You can set the hook to run a command like npm run lint or pytest on the specific files that were just touched. If the script exits with an error code, you will know right away that the agent has introduced a regression. This prevents the agent from building a long chain of dependent changes on top of a broken foundation. It also saves you from the tedious task of manually verifying every single file modification during a long interactive session.
Visualize automated workflows across multiple projects
When you are running multiple Claude Code sessions simultaneously, keeping track of which hooks are running and which projects are currently passing their automated checks becomes difficult. This is where adhdTerminal provides a significant advantage for your daily workflow. It runs many sessions side by side, with each one appearing as a distinct tile on a wall. Each tile has a color, a number, and a name, making it easy to distinguish between a backend refactoring task and a frontend styling session at a single glance.
The interface of adhdTerminal shows whether a specific tile is currently working, waiting for your input, or idle. If a hook is triggered and starts a long-running build or a heavy test suite, the tile status reflects that activity. You can see the last exchanges of the conversation directly on the tile, which helps you monitor the progress of the agent alongside the results of your automated scripts. This high-level view allows you to manage several complex automation pipelines without losing track of the state of any individual project.
Manage script execution and session interruptions
Sometimes a script triggered by a hook might take longer than expected or encounter a problem that causes it to hang. In these situations, you need a way to regain control of the terminal session without losing your progress. You can press the Escape key once to interrupt what the agent or the hook script is currently doing. This is an essential safety mechanism when you are testing new automation scripts that might have unexpected side effects or long execution times in certain project environments.
If a hook script fails or if you need to revert to a previous state in the conversation after a bad automated change, you can press the Escape key twice. This action offers you a list of earlier messages, allowing you to go back to a point before the error occurred. For more persistent issues with your environment or installation, you can run the claude doctor command to check the health of your setup. This command helps verify that your shell environment and the CLI are communicating correctly, which is vital for scripts that rely on specific environment variables or path configurations.
Maintain project state with session start and end hooks
The SessionStart and SessionEnd hooks are perfect for managing the broader context of a coding task. You might want to use SessionStart to automatically create a new git branch for the agent to work on, ensuring that no changes are made directly to your main branch. This setup provides a clean sandbox for the agent and makes it easier to review its work later. Similarly, you can use SessionEnd to run a final comprehensive test suite or to generate a summary of the changes made during the session using the TodoWrite tool to update a progress log.
These lifecycle hooks allow you to treat every interaction with Claude Code as a structured transaction. When the session begins, your environment is prepared according to your exact specifications. When you quit the session using Ctrl-C or when it finishes its assigned task, the cleanup scripts ensure that no temporary files are left behind and that all relevant notifications are sent. This level of automation turns the CLI into a more integrated part of your professional toolchain rather than just an isolated command line utility.
Control permissions for automated shell commands
Security is a major consideration when allowing an agent to trigger shell scripts automatically. Claude Code has different permission modes that change how it handles tool execution and hooks. By default, the system may ask for your approval before running certain commands that could modify your system. If you want a more hands-off experience where your hooks run without constant confirmation, you can use Shift-Tab inside a session to cycle through the permission modes. Switching to the bypassPermissions mode allows the agent and your hooks to run with fewer interruptions.
You can also fine-tune these permissions in your settings.json file under the permissions key. This allows you to allow or deny specific tools or scripts on a per-project basis. For example, you might want to allow the Read tool to run without confirmation but require a manual check for the Write tool or for certain Bash commands triggered by hooks. Balancing these settings ensures that your automation remains powerful while still giving you the necessary oversight to prevent unwanted changes to your local file system or project structure.
Advanced logging and notification strategies
The Notification hook is a versatile tool for keeping yourself informed about the progress of long-running tasks. You can configure this hook to send a message to your system's notification center or a team chat platform whenever the agent reaches a significant milestone. This is particularly useful if you are working away from your desk or if you are using the adhdTerminal iPhone app to mirror your wall. The mobile app can receive these updates over an end to end encrypted link, letting you know the second a task is done or if it needs your attention.
Combined with the status updates shown on each tile, these notifications provide a comprehensive monitoring system for your development work. You can trigger a hook on SubagentStop to log the results of a specific sub-task or use the PreCompact hook to save a snapshot of the session context before it is summarized. By using these hooks to feed data into your own logging or monitoring tools, you create a transparent and traceable record of everything the agent does. This makes it much easier to debug complex issues and to share the progress of automated tasks with the rest of your team.
Questions people ask
Can a hook script access the output of the previous agent command?
Yes, many hooks provide context about the preceding event through environment variables or standard input streams depending on your shell setup. For example, during PostToolUse, your script can be designed to check the exit status of the tool that just ran to decide whether to continue with a build or stop the process. You should test your specific scripts using a simple log command to see exactly what data is available during each hook event.
What happens if my hook script requires user input?
Hook scripts that require interactive user input can sometimes cause the session to appear frozen because the agent is waiting for the script to finish. It is best to design your hooks to be non-interactive by using flags like -y or by piping in the necessary responses. If a script does get stuck, you can use the Escape key to interrupt the process and return to the interactive prompt.
Can I run multiple shell commands in a single hook definition?
You can run multiple commands by combining them with standard shell operators like && or ; inside the JSON string in your settings file. For example, you could set a hook to run a build command followed by a notification script. For more complex logic, it is usually cleaner to put all the commands into a single shell script file and then call that file from the hook definition.
Read next
- Add build instructions to your CLAUDE.md fileImprove project context by adding specific build commands and environment requirements to your CLAUDE.md file for the AI to follow.
- Add common error fixes to CLAUDE.mdImprove project memory by adding a section for common errors and their fixes to your CLAUDE.md configuration file.
- Add custom shell aliases for Claude CodeSpeed up your workflow by creating shell aliases for common Claude Code invocations and project-specific startup commands.
- Add test commands to a CLAUDE.md fileUnderstand how to define specific test runners and environment flags in your CLAUDE.md file so the tool runs the correct test suite.