Try free

Last updated 13 October 2026

How to use pre-task hooks in Claude Code

Automating your environment preparation

When you launch Claude Code to fix a bug or add a feature, your development environment must be ready for the task. You likely waste time checking if you have the latest code from the main branch or if your local database is running. If you forget these steps, the agent might fail to run tests or get stuck on errors that you already fixed in a different branch. You want the agent to handle these prerequisites automatically before it begins thinking about your prompt.

Automating these checks prevents the agent from wasting your budget on avoidable errors. Instead of manually running shell scripts before every session, you can define specific events that trigger scripts. This ensures that every time you submit a task, the codebase is in a known good state. This reliability is essential when you manage many different projects simultaneously and cannot remember the unique setup requirements for each one. Using hooks makes the agent a more capable partner in your daily workflow.

Defining hooks in your configuration files

Claude Code looks for automation instructions in your configuration files to understand how to handle specific events. You can place these instructions in your project root at .claude/settings.json or in your home directory at ~/.claude/settings.json for global rules. The configuration uses a specific section for hooks where you map event names to the actions you want the agent to take. These actions usually involve running a command in the shell to prepare the system.

The hook system uses specific event names such as UserPromptSubmit and PreToolUse. When you type a request and hit enter, the UserPromptSubmit event fires immediately. This is the best moment to run a script that checks for missing dependencies or outdated build artifacts. You define the hook by specifying the event name and then providing the script or command you want to execute. The agent will follow these instructions every time the event occurs during your session.

Implementing the UserPromptSubmit hook for pre-task checks

To implement a pre-task script, open your .claude/settings.json file and locate the hooks section. Inside this section, add an entry for UserPromptSubmit. You can tell the agent to run a shell command such as a git pull or a linting check. This ensures that the agent always works on the most recent version of your code without you having to remember to update it manually. You can even chain commands together to perform a series of health checks before the agent starts its work.

You must be careful about the duration of these scripts. If a hook takes too long to run, it adds latency to every interaction you have with the agent. If your setup script is heavy, consider adding logic that only runs the full installation if a configuration file has changed recently. Use the Bash tool within the hook definition to execute your commands. This keeps the automation integrated within the standard Claude Code workflow and allows you to see the output of the setup process in your terminal.

Managing multiple projects with adhdTerminal

When you use hooks across many different repositories, keeping track of which session is currently running a setup script becomes difficult. adhdTerminal helps you manage this by displaying multiple Claude Code sessions as tiles on a wall. Each tile can have its own color, number, and name, allowing you to see at a glance which project is currently running a pre-task hook. This is especially useful if you are waiting for several heavy build processes to finish across different parts of a microservices architecture.

If a hook fails or takes a long time, the tile in adhdTerminal shows whether the session is working, waiting for you, or idle. You can monitor the progress of several automated setups simultaneously without switching between multiple terminal tabs. This visibility is helpful when you are coordinating changes across a complex system. A free iPhone app mirrors the wall over an end to end encrypted link, so you can check if your pre-task hooks finished while you are away from your desk.

Using PreToolUse for granular task control

While UserPromptSubmit runs before the agent processes your words, PreToolUse runs before the agent executes a specific tool like Read or Edit. This is useful if you want to ensure a file is not locked or a specific service is available only when the agent actually needs to use it. It provides a more targeted way to manage the lifecycle of a task compared to a blanket start-up script. You can configure this hook to trigger only for certain tools that you know require environment prep.

Setting up a PreToolUse hook requires you to specify which tool triggers the action. For example, if the agent decides to use the Read tool on a specific directory, you can trigger a script that generates fresh documentation or exports a database schema. This ensures the data the agent reads is always current and accurate. It prevents the agent from making decisions based on stale information which would lead to incorrect code edits and wasted time.

Validating your hook configuration and syntax

After you modify your settings.json file, you should verify that Claude Code recognizes your changes correctly. You can run the /doctor command inside an active session to check the health of your installation and configuration. If there is a syntax error in your JSON file, the /doctor command will highlight the issue so you can fix it. This is much faster than waiting for a hook to fail during a critical task when you are trying to be productive.

You can also use the /hooks command to see a list of all active hooks in your current session. This command tells you exactly which scripts are registered for each event. If you find that a hook is causing problems or is no longer necessary for your project, you can modify the settings.json and the changes will take effect in your next session. Keeping your hooks lean and testing them regularly ensures a smooth and predictable experience during development.

Handling permissions and safety for automated scripts

Hooks run with the permissions you have defined in your settings. If your hook requires sensitive operations, ensure your permission modes allow it. You can cycle through modes like default, acceptEdits, plan, and bypassPermissions using Shift+Tab inside the session. If you are in a mode that requires approval for every tool use, the agent will ask for your consent before running the hook script. This provides a safety layer to prevent unauthorized commands from running without your knowledge.

You can configure per-tool permissions in your settings.json file under the permissions section. This allows you to grant the Bash tool more freedom for specific hooks while maintaining strict control over other operations like Write or Edit. Balancing automation and safety is key to a productive setup. If a hook ever gets stuck or behaves unexpectedly, you can press the Escape key once to interrupt the process and regain control of the terminal.

Refining instructions with CLAUDE.md documentation

While hooks handle the execution of scripts, the CLAUDE.md file provides the context the agent needs to understand those scripts. You should document your environment setup and the purpose of your hooks in the CLAUDE.md file at the root of your repository. This helps the agent understand why a specific script ran and how to interpret the results if the script fails. You can also place subdirectory-specific instructions in a CLAUDE.md file within those folders.

A well-maintained CLAUDE.md works alongside your hooks to create a self-correcting environment. If a pre-task hook fails, the agent can read the instructions in CLAUDE.md to find troubleshooting steps or alternative commands. This combination of automated triggers and clear documentation reduces the amount of manual intervention you need to provide. It allows the agent to be more autonomous and effective in managing your development tasks while you focus on higher level design.

Questions people ask

Can I run multiple commands in a single hook event?

Yes, you can run multiple commands by joining them with standard shell operators like && or ; in your hook definition. This allows you to perform a sequence of tasks such as pulling code and then installing dependencies in one go. Make sure the logic is robust so the entire chain does not fail because of a minor warning.

Do hooks work when I use the -p flag to run a single prompt?

Yes, hooks like UserPromptSubmit and SessionStart will still trigger when you run a command using claude -p. This ensures that even one-off commands benefit from your environment preparation scripts. It is a reliable way to make sure your quick checks are always performed against the latest version of your code.

How can I stop a hook that is taking too long to finish?

You can press the Escape key once to interrupt the current operation, including a running hook. If the entire session becomes unresponsive, you can use Ctrl+C to quit the agent completely. If you find yourself doing this often, you should optimize your hook scripts or move them to a less frequent event.

Read next

More on claude code basics·All posts