Last updated 13 October 2026
Run npm install using Claude hooks
The friction of manual dependency management
You are deep in a coding session when Claude Code decides to add a new library to your project. It successfully uses the Edit tool to update your package file, but then it stops. You have to manually type the command to install the new dependencies before you can run your tests or start the dev server. This interruption breaks your flow and forces you to manage the environment yourself when the agent should handle the entire lifecycle of the change. This manual step is especially annoying when you are working across multiple microservices or monorepos where each change might require a different installer or a specific set of flags.
The problem is not just the typing but the context switching. Every time you leave the prompt to run a shell command, you risk losing the thread of the problem you are solving. If the agent modifies the package file and you forget to install the updates, your next test run will fail with a module not found error. This leads to a cycle of failure and correction that wastes time and computational resources. You want the agent to be smart enough to know that a change to the configuration of your project requires an immediate update to the local environment without you having to ask for it every single time.
Understanding the lifecycle of tool execution
Claude Code operates by selecting specific tools to interact with your file system and terminal. When it needs to change a file, it usually calls the Edit tool or the Write tool. These actions are isolated events in the conversation history. To bridge the gap between a file edit and a shell command, you must use the internal hook system. This system allows you to define specific actions that trigger based on events in the lifecycle of the agent. The most relevant event for this task is the one that occurs immediately after a tool has finished its work. This event provides the necessary context to determine what happened and what should happen next.
By tapping into the PostToolUse hook, you can inspect the result of the previous action. This hook is powerful because it gives you access to the name of the tool that was just run and the arguments that were passed to it. If the Edit tool was used to target a file named package.json, you have the signal you need to trigger a follow-up action. This creates a chain of events where the completion of one task automatically initiates the next logical step in the development process. You are essentially teaching the agent the standard operating procedures of your specific tech stack.
Configuring hooks in the project settings
To start automating your workflow, you need to modify the settings file. You have two main options for where to place these configurations. If you want the automation to apply to every project you work on, you should edit the settings.json file located in your user directory. However, for project-specific needs like running npm install, it is better to use the .claude/settings.json file within your repository root. This ensures that the automation only triggers in environments where the package manager is actually present and relevant. If a project does not have this file, you can create it to start customizing the agent behavior for that specific codebase.
Inside the settings file, you will find or create a section dedicated to hooks. This is where you map specific events to the commands you want to run. You must define a listener for the PostToolUse event. The configuration requires you to specify a command that the system will execute whenever any tool finishes. Because this hook runs after every tool use, you cannot simply put a blind install command there. Doing so would cause the agent to run a heavy installation process every time it reads a file or lists a directory. You need to provide a script or a conditional check that looks for the specific file changes you care about before proceeding with the installation.
Filtering for specific file changes
The logic for your hook should be concise but effective. Since the hook provides environment variables or data structures representing the tool call, you can check if the tool name matches Edit or Write. Once you confirm the tool type, you check the file path argument. If the path points to package.json, your script should then trigger the Bash tool to execute the install command. This conditional logic ensures that the automation is surgical. It only fires when a dependency change is actually detected, keeping the overhead of your development session as low as possible while still providing the automation you need.
It is helpful to consider the different package managers you might use. If your project uses Yarn or Bun instead of npm, you would adjust the terminal command accordingly in your hook definition. You can even make the script robust enough to check for a lock file to decide which manager to use. This level of automation turns the agent into a more integrated part of your development environment. Instead of just being a script that writes code, it becomes a system that maintains the health of your project. When the agent sees that a tool call has modified the manifest, it takes the initiative to sync the node modules folder automatically.
Managing tool permissions and security levels
When you automate shell commands through hooks, you must consider the permission model of Claude Code. By default, the agent will ask for your permission before running a bash command that it generated. This is a safety feature to prevent unintended or harmful code from executing on your machine. If your hook triggers the Bash tool, you might see a prompt in the terminal asking you to allow the operation. If you find this prompt repetitive for a trusted command like npm install, you can adjust the permission settings in your settings.json file. You can set the Bash tool to be allowed automatically for specific commands or within specific projects.
Using the bypassPermissions mode is another way to handle this, though it should be used with caution. In this mode, the agent will proceed with tool execution without waiting for your input. This makes the automation truly hands-off. If you are confident in your hook logic and the project environment, cycling to this mode with Shift+Tab can make the experience much smoother. However, for most developers, keeping the default permission level and just hitting enter to confirm the install is a good middle ground. It provides a moment of verification to ensure the agent is not doing something unexpected while still saving you from having to type the command yourself.
Enhancing project instructions with CLAUDE.md
While hooks handle the automatic execution, your CLAUDE.md file should provide the context for why these things are happening. This file is the primary source of truth for project-specific instructions. You should add a section in CLAUDE.md that describes the automated setup. This helps the agent understand that it does not need to manually suggest running an install after it edits a file because a hook is already in place to handle it. This prevents the agent from wasting tokens on unnecessary suggestions and keeps the conversation focused on the actual coding task at hand.
You can also use CLAUDE.md to define custom scripts that the hook can call. For example, if your installation process involves more than just a simple npm install, such as generating types or compiling a local library, you can document that process. The agent will read these instructions and can even help you debug the hook if it fails. By combining the proactive nature of hooks with the clear instructions in your project root, you create a robust environment where the agent knows exactly how to keep your workspace in a ready-to-run state. This synergy between settings and documentation is what makes advanced agent usage so effective.
Monitoring multiple sessions with adhdTerminal
As you start using more hooks and automations, you might find yourself running several Claude Code sessions at once to handle different features or microservices. Managing multiple terminal tabs where background installs are happening can get confusing. This is where adhdTerminal becomes a useful addition to your toolkit. adhdTerminal is a native app for macOS and Windows, made by MINDBALANCER OU in Estonia, and it is not affiliated with Anthropic. It runs many sessions side by side, with each one appearing as a tile on a wall. This allows you to see the status of your automated hooks across every project simultaneously.
Each tile in adhdTerminal has a color, a number, and a name, and it shows whether the session is working, waiting for you, done, or idle. When your npm install hook triggers in a background session, the tile will show that it is working. You can see the last few exchanges of the conversation and even numbers or headlines the project publishes. This visibility is vital when you have background tasks running. If an installation fails due to a network error or a version conflict, you will see it immediately on your wall of tiles without having to manually check each open terminal window. It keeps your automated workflow transparent and manageable.
Handling complex install scripts and edge cases
Not every package installation is straightforward. Some projects require environment variables to be set, or they might need a specific version of Node.js managed through a version manager. When you write your hook, you should account for these requirements. You can wrap your install command in a script that sources the necessary profile files or checks the current environment. This ensures that the Bash tool runs the install command in a context that matches your manual terminal environment. If the hook fails, you can use the Notification hook event to send a message to yourself or log the error to a specific file for later review.
You should also consider what happens if multiple files are changed in a single tool call. If the agent uses the Write tool to create a new project structure that includes a package.json, the hook will trigger as expected. However, if the agent is performing a large refactor and hits the context limit, you might need to use the /compact command. This command summarizes the session and frees up space. It is a good idea to ensure your hooks do not interfere with the compacting process. By keeping your hook logic external to the main conversation flow and focusing on the tool output, you maintain a clean and efficient session regardless of the project size.
Streamlining the developer experience
Automating the mundane parts of your development cycle allows you to focus on high-level architecture and complex logic. When you no longer have to worry about whether your local environment matches your configuration files, you can move much faster. The combination of Claude Code for the heavy lifting of coding and custom hooks for environment maintenance creates a powerful synergy. You are no longer just a user of an AI tool; you are an orchestrator of an automated development system that understands the needs of your specific project.
To keep this system running smoothly, remember to occasionally run the claude update command to get the latest features and improvements to the hook system. You can also use claude doctor to check if your installation and path configurations are correct if you notice any hooks failing to trigger. By taking the time to set up these automations today, you save yourself hours of repetitive work over the life of your project. The goal is to reach a state where the agent handles the entire implementation detail, from the first line of code to the final successful installation of the necessary dependencies.
Questions people ask
Will the npm install hook run every time I edit any file?
No, it will only run if you include logic in your hook to check the file path. By inspecting the arguments of the Edit or Write tool within the hook, you can ensure the command only executes when package.json is specifically modified. This prevents unnecessary overhead during regular coding tasks.
Can I use this to run other commands like database migrations?
Yes, you can apply the same logic to any configuration file. For example, if the agent modifies a schema file or a migration directory, you can set a hook to run the corresponding migration command via the Bash tool. This ensures your local database always stays in sync with your code changes.
What happens if the npm install command fails during the hook?
If the command fails, the error will typically be reported back into the session as a tool error. You will see the output in your terminal, and the agent will be aware that the installation did not succeed. You can then ask the agent to fix the dependency issue or manually intervene to resolve the conflict.
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.