Last updated 13 October 2026
Claude Code cannot find local npm binaries
The environment gap between host and agent
Claude Code initiates a subshell to run the Bash tool whenever it needs to execute a command. When you run a command in your terminal, your shell configuration files like .zshrc or .bashrc provide a PATH that includes local node modules. Claude Code might not inherit this entire environment because it runs as a separate process. This leads to errors where the agent claims a binary like npx or vitest does not exist, even though you just ran it yourself seconds ago. The agent relies on the environment it was spawned in, but its internal Bash tool usage can behave differently than an interactive login shell.
The primary reason for this discrepancy is the way shell profiles are loaded. Non-interactive shells often skip the files where you define your PATH additions. If your npm binaries are added via a tool like nvm or asdf, those tools require specific initialization code that might not be running inside the Claude Code session. This results in the agent having a very basic PATH that only includes system defaults. To fix this, you must ensure that the environment where you launch the claude command already has all the necessary paths exported and available to child processes.
Diagnose the path with the doctor command
The first step in resolving path issues involves checking how the agent sees the system. Run claude doctor from your terminal to see the current state of the installation and environment. This utility checks if the basic requirements are met and if the agent can access its own configuration files. However, it might not show the specific PATH available to the Bash tool inside an active session. You need to verify what the agent actually sees when it tries to work.
To see the internal path, you should start a session with the claude command and ask the agent to run a command like printenv or echo $PATH using its Bash tool. This reveals exactly which directories the agent searches when it tries to execute npx or other binaries. If you see that your node-modules folder or your global npm bin folder is missing from that list, you have identified the root cause. You can then take steps to inject that path into the agent context through configuration files or explicit instructions.
Configure project instructions in CLAUDE.md
You can solve many path issues by writing specific instructions in the CLAUDE.md file at the root of your project. Tell the agent explicitly that it should look for binaries in the local node-modules directory. Instruct it to prefer the full path ./node-modules/.bin/ followed by the command name instead of relying on a global installation. Since Claude Code reads CLAUDE.md at the start of every session, these instructions become part of its standard operating procedure for your repository. This prevents the agent from wasting time trying to install packages globally when they already exist locally.
If your project has a unique structure, you can place a CLAUDE.md file in a subdirectory to apply specific rules to that part of the tree. For example, if you have a monorepo, a CLAUDE.md file inside a specific package folder can tell the agent to use the binaries local to that package. This granular control ensures that the agent always uses the correct version of a tool, even if multiple versions exist across your repository. Explicitly naming the local path in these files is the most reliable way to guide the agent.
Use terminal setup to align shell environments
The /terminal-setup command inside a session helps the agent understand how to interact with your specific shell. If your local npm binaries require specific environment variables or a modified PATH to function, this is a good place to start the troubleshooting process. You can also use the /config command to check current settings and see if there are any overrides affecting how the agent handles the shell. If the agent repeatedly fails to find tools, you might need to adjust how your shell exports these paths so they are available to non-interactive shells.
Many developers find that their local path logic is trapped in shell configuration files that only run for interactive sessions. This leaves the Claude Code Bash tool without the necessary context. To fix this, move your PATH exports to a file that is loaded for all shell instances, or ensure that you are exporting the variables correctly before you run the claude command. If you use a version manager for Node.js, ensure it is configured to work with non-interactive shells so that the agent can find the correct node and npm binaries automatically.
Manage tool permissions for execution
Sometimes the issue is not just the path but the permission to run the tool. Check your local .claude/settings.json file or the global ~/.claude/settings.json file. You can find a permissions section where you can allow or deny specific tools like the Bash tool or the Edit tool. If the Bash tool is restricted, the agent might not be able to execute scripts even if it finds them. You can manage these settings to give the agent the necessary level of access for your project.
The permission mode also plays a role in how binaries are executed. You can cycle through modes using Shift+Tab to reach the default or acceptEdits mode. In these modes, the agent has more freedom to run the Bash tool and interact with your files. If you are in plan mode, the agent might only suggest a command but not actually try to run it, which can sometimes look like a failure to find the binary. Always check which mode you are in if the agent seems hesitant to execute a local script.
Automation with hook events
Claude Code supports hooks that trigger on specific events like SessionStart or PreToolUse. The SessionStart hook is particularly useful for setting up a local environment. You can define a hook that runs a command to export the local bin folder to the PATH every time a session begins. This ensures that every subsequent call to the Bash tool has the correct context without you needing to type it every time. You define these hooks in your settings.json file.
By using the PreToolUse hook, you could even check for the existence of node-modules before the agent tries to run an npm command. This level of automation keeps the workflow smooth without manual path declarations in every prompt. Hooks allow you to customize the agent behavior to match the specific needs of your development environment. If you find yourself repeatedly telling the agent where npx is, a hook is the correct way to automate that instruction and save time in every future session.
Visualizing multiple project environments
When you work on several Javascript projects simultaneously, each with different node versions or binary paths, managing them in a single terminal window becomes difficult. This is where adhdTerminal provides a significant advantage. It is a native app for macOS and Windows, made by MINDBALANCER OU in Estonia, and it is not affiliated with Anthropic. It runs many Claude Code sessions side by side, where each one is a tile on a wall. A tile has a colour, a number, and a name, and it shows the last exchanges of its conversation. This visual separation prevents environment contamination between projects.
Tiles in adhdTerminal show whether they are working, waiting for you, done, or idle. They can even show numbers and headlines that your project publishes. The app ensures that tiles reopen in the same place after a restart and resume the same session automatically. This is especially helpful when you are debugging npm binary issues across a large monorepo. Instead of constantly switching directories and running claude --continue in different terminal tabs, you can see all your active agents at once.
Execute precise prompts for binary discovery
If the agent still struggles to find npx, you can give it a direct task using the -p flag. Running a command like claude -p 'find the path to npx and run a build' forces the agent to look for the binary before it gives up. This one-off prompt can sometimes bypass environment issues that persist in an interactive session. Within an active session, you can use the /memory command to see if the agent has stored an incorrect path or a failed state in its current context.
If the agent has internalised a wrong path, use the /clear command to start over in the same folder. This wipes the current conversation but keeps you in the project. Sometimes the agent gets stuck in a loop trying the same failing command, and a quick session reset is the fastest way to apply new path configurations. You can also use claude --resume to pick an earlier session from a list if you need to go back to a point before the path issues began.
Mirroring the environment for mobile work
Sometimes you need to kick off a build or run a test suite while away from your desk. A free iPhone app mirrors the adhdTerminal wall over an end-to-end encrypted link. If a local npm binary fails or an environment error pops up while you are mobile, you can see it on your phone immediately. You can answer a prompt or send the next task to fix the path issue directly from the app. This ensures that your development pipeline does not stall just because a path variable needed a manual override.
The adhdTerminal app costs 99 dollars once. One key runs one computer at a time and can be moved, and it comes with a 7 day free trial and no account. It provides a way to keep your local builds moving forward without being tethered to your workstation. Being able to check the status of a long-running test process from your phone, and correcting the agent if it loses its way, makes the development process much more flexible. It turns a stationary terminal task into a portable workflow.
Questions people ask
Why does npx work in my terminal but not inside Claude Code?
Claude Code runs the Bash tool in a subshell that might not load your interactive profile files. This means changes to your PATH in .zshrc or .bashrc are often ignored by the agent. You should export these paths globally or define them in your CLAUDE.md file to ensure they are visible.
Can I force the agent to use a specific node version?
Yes, you can specify the node version in your project CLAUDE.md file. Instruct the agent to use a specific path for the node binary or to run a version manager command before executing any npm scripts. This ensures the agent uses the same environment you use for manual development tasks.
What should I do if /terminal-setup does not fix the path?
Use the /config command to check your settings.json and ensure there are no conflicting path overrides. If that fails, define a SessionStart hook to manually append the correct directories to the PATH variable every time a session begins. This bypasses shell initialization issues by setting the environment variables directly through the agent context.
Read next
- Access git submodules in Claude CodeFix issues where Claude Code cannot see or modify code located inside nested git submodules within your main repository.
- Allow Claude Code to run shell scriptsResolve tool execution errors by adjusting permission settings to let Claude Code execute local bash or powershell scripts in your terminal.
- Break a linter error loop in ClaudeWhat to do when Claude Code fixes one linting error only to create another, leading to a circular set of edits.
- Change the Node version for Claude CodeResolve compatibility issues by switching the Node.js version used by Claude Code without breaking your other local development tools.