command not found after npm install -g: your terminal and the AI agent are using different Node installs
Frank Zhang
- 4 minutes read - 1952 wordsTL;DR
A global install can succeed and still be invisible to an AI agent, a script, or zsh -lc. Compare which node, which npm, and npm prefix -g in the interactive terminal and in the shell that failed.
After npm install -g on a Mac, command not found usually means the binary landed in one Node prefix and the shell that failed is using another. That is not proof the install failed, and it is not proof the agent is dumb. Terminal, an AI agent, a script, zsh -lc, and a command runner inside Cursor or VS Code are separate processes. On a machine with both Homebrew and nvm, they often do not share a Node.
People search that as npm: command not found or zsh: command not found: npm in Terminal, zsh, or VS Code, often with nvm, Homebrew, or Cursor in the query, and as command not found after npm install -g when the missing name is yarn, vite, claude, or another CLI. The worked example is agent-browser, which Codex could not see in March 2026. The mechanism is the prefix.
These commands were not re-run for this page. Which startup files zsh reads comes from the zsh manual as read for this page. What -g writes comes from the npm docs as read for this page. The paths below are the ones the March 2026 note already recorded.
Thirty seconds
| What is on screen | What it is saying | First read-only check, in the shell that failed |
|---|---|---|
zsh: command not found: npm, or npm: command not found, in Terminal, zsh, VS Code, or Cursor | This shell has no npm on PATH. | which -a node npm |
<name>: command not found after npm install -g <name> (yarn, vite, claude, or another CLI) | npm did run. The binary is not in the prefix this shell is using. | npm prefix -g and command -v <name> |
| The interactive terminal can run it, and the agent or the script cannot | Those two shells are not using the same Node. | The same four commands in the interactive terminal, then the zsh -lc line below |
A local npm install with no -g is a different layout. npm’s folders page says local executables are linked into ./node_modules/.bin. A new shell does not search that directory. This page is the -g case: the install used a global prefix, and the failing shell is on a different one.
What -g writes
npm’s folders page says a global install puts files in /usr/local or wherever that Node is installed. The prefix config defaults to the location where node is installed. On most systems the documented default is /usr/local. On Unix, node is typically {prefix}/bin/node, one level up from the binary. With the global flag, packages go to {prefix}/lib/node_modules and executables are linked into {prefix}/bin. That {prefix}/bin directory has to be on PATH.
npm prefix prints the local prefix, the closest parent with a package.json or a node_modules directory, unless -g is set. With -g it prints the global prefix. The example on that page is /usr/local. That string is the documentation’s example, not a measurement from the Mac below. npm root prints the effective node_modules folder, and npm root -g is the global one.
“Global” means this npm’s prefix. Two npm binaries are two places a CLI can land. The agent in the note resolved node and npm under /opt/homebrew/bin, Homebrew’s Apple Silicon location. This page does not add an Intel /usr/local measurement for that machine.
Read both shells before you change either Node
Nothing in this section edits ~/.zshrc, installs a package, or removes a Node. Run the reads in the shell that failed, then again in the interactive terminal where the install seemed to work.
which -a node npm
npm prefix -g
command -v agent-browser
Put the CLI’s real name in place of agent-browser. which -a lists every match, so a second Node on PATH still shows up. npm prefix -g is the prefix of the npm this shell just ran. command -v says whether this shell can resolve the CLI.
The four checks I run before trusting a global CLI are the same questions, one name at a time:
which node
which npm
npm prefix -g
command -v agent-browser
When the tool is for an agent, a script, or any other automation, ask again in a login shell that runs one command:
zsh -lc 'which node; which npm; npm prefix -g; command -v agent-browser'
echo $PATH and type node npm are optional, and they still write nothing. echo $PATH prints this shell’s search path. type reports whether node and npm are functions, aliases, or external commands. A lazy wrapper makes the name a function in the interactive shell that defined it. The March note has no type or PATH transcript.
A different node, a different npm, or a different npm prefix -g is the disagreement that matters. The same user, the same PATH, and the same prefix should make command -v agree in another tmux pane and another directory. Compare before you uninstall anything.
What the March 2026 note recorded
Codex reported agent-browser: command not found. ~/.zsh_history already contained a successful install and a short manual run:
npm install -g agent-browser
agent-browser install
agent-browser --version
agent-browser open https://www.google.com
agent-browser snapshot
agent-browser close
The copy from that earlier session was on disk under nvm’s Node 20:
~/.nvm/versions/node/v20.19.5/bin/agent-browser
~/.nvm/versions/node/v20.19.5/lib/node_modules/agent-browser
Those are {prefix}/bin and {prefix}/lib/node_modules from the folders page, with the prefix ~/.nvm/versions/node/v20.19.5.
The agent environment’s which was not that tree:
which node → /opt/homebrew/bin/node
which npm → /opt/homebrew/bin/npm
That is Homebrew’s node and npm, not ~/.nvm/.../bin/node. The history and the agent’s lookup were both real. They were aimed at different prefixes. This page did not re-run which, npm prefix -g, or agent-browser, and it does not add an npm prefix -g line the note never wrote down.
Why the interactive terminal and the agent diverged
~/.zshrc had a lazy-load nvm wrapper. nvm was not initialized when the shell started. Typing node, npm, or npx in an interactive terminal switched to the nvm Node. The agent, scripts, and zsh -lc did not receive those wrapper functions, and they stayed on Homebrew.
That lines up with the files zsh reads. The startup files section reads $ZDOTDIR/.zshenv for every shell, using HOME when ZDOTDIR is unset. A login shell then reads /etc/zprofile and $ZDOTDIR/.zprofile. An interactive shell reads /etc/zshrc and $ZDOTDIR/.zshrc. A login shell then reads /etc/zlogin and $ZDOTDIR/.zlogin. ~/.zshrc is the interactive file. This page does not inventory ~/.zshenv, ~/.zprofile, or ~/.zlogin.
Invocation says -c takes the first argument as a command. The options page says LOGIN (-l) marks a login shell, and INTERACTIVE is set when standard input is a tty and commands are being read from standard input, unless the command line sets it. SHIN_STDIN says commands come from standard input when no -c command and no script file were given. zsh -lc '...' is a login shell running one command, so the interactive heuristic does not apply and ~/.zshrc is not read. The login files are. A non-interactive agent or script misses ~/.zshrc the same way, unless some other file sources it.
nvm exists only in a shell that sourced it. The nvm README, as read for this page, says to activate nvm by sourcing it (. ./nvm.sh), and to put the nvm.sh source lines in ~/.bashrc, ~/.profile, or ~/.zshrc so they run for a login. The same page says which nvm will not work, because nvm is a sourced shell function, not an executable binary, and it gives command -v nvm as the check. The function, and the PATH change it performs, live in the shell that sourced nvm.sh. The README’s login snippet does not by itself load nvm into a non-interactive zsh that skips ~/.zshrc.
fnm, volta, and asdf are the same class of tool when they put a Node on PATH only in shells that load their hook. The case written down here was nvm plus Homebrew.
A different tmux pane, or a different working directory, stays consistent when the user, the PATH, and the prefix are the same. command -v agent-browser should then agree. The recorded split was which startup files ran, and therefore which Node prefix the shell kept.
Many agents run a non-interactive shell, or a login shell that is not the interactive Terminal session where npm install -g was typed. Cursor, VS Code, and Claude belong in that general group. This page does not record a separate incident for any of them. A related split, for SSH keys rather than PATH, is Permission denied (publickey) for git@github.com on a Mac: the server refused every offered key.
When the two prefixes disagree
Compare the shells first. Then choose which Node the failing command should see. Two approaches both work.
Sourcing nvm in the non-interactive environment is valid general guidance. The shell that will run node and npm has to source nvm.sh, in the same invocation if the session is only one command. This page does not say I did that.
What I chose for the normal workflow was a single default Node:
- Homebrew’s
node,npm, andnpxare the default for ordinary commands. - nvm stays installed, and it is used when a version switch is explicit.
~/.zshrcstops shadowingnode,npm, andnpx.
The interactive shell, a new tmux pane, the agent, and a non-interactive script then see the same binaries and the same global directory. One default is the layout I picked. Two Node installs still work when every shell that must see the CLI uses the npm that installed it.
If command -v still misses the CLI in the shell that has to run it, install it again with the npm that shell’s which npm printed. That writes {prefix}/bin for the prefix you just identified. Do it after the read-only comparison, and leave the other Node in place.
What to leave alone
Leave both Node installs on disk until which -a node npm and npm prefix -g have been read in the interactive terminal and in the failing shell. rm -rf ~/.nvm, uninstalling a Node, or replacing a default Node is not the first step. The other Node install is part of the evidence.
sudo npm install -g is not the fix. It runs whichever npm root’s PATH resolves, and it writes that prefix as root. It does not copy a binary from the nvm prefix into the Homebrew prefix, or the other way around.
A finished npm install -g in the terminal you type in describes that shell’s prefix. The history can be accurate while command -v in the agent’s shell still fails.
Where this page stops
- The commands were not re-run for this page. The history lines, the two paths under
~/.nvm/versions/node/v20.19.5, and the agent’s/opt/homebrew/bin/nodeand/opt/homebrew/bin/npmare the March 2026 note. There is no new timing, version, ornpm prefix -gtranscript here. - The zsh pages linked above are the ones read for this summary.
man zshon the machine in front of you is that machine’s copy. - The npm pages linked above are the v11 docs as read for this page. Their
/usr/localexample is not this Mac. - On Windows, the folders page gives the global prefix as
%AppData%\npm. This page does not walk through Windows or Linux. - Cursor, VS Code, and Claude appear here only as programs that often run a non-interactive shell. No separate incident is recorded for them.
- Search volume is not measured here.
The Chinese writeup of the same incident is 明明全局安装了 agent-browser,为什么 AI 代理还是说“找不到”?. Whether a project should be deployed at all is a separate list: 10 things to confirm before deploying a GitHub project. Other paths on the site start at Start Here. The Chinese reading route is 自部署阅读路线.
If this post helps, you can sponsor the blog. This is voluntary personal support, not a charitable donation.