claude-code - 💡(How to fix) Fix /doctor false positive: 'npm-global' detected when npm prefix shares directory with native install

Summary

claude /doctor reports a "Multiple installations found" + "Leftover npm global installation" warning when the npm global prefix is set to a directory that happens to also contain Claude Code's native install symlink. The warning is a false positive — there is no actual npm package installed.

Environment

• Claude Code: native 2.1.150 (commit 28d4819e0f0a)
• OS: Linux x64 (Ubuntu 24.04.4)
• Install method: native installer

Reproduction

1. Set npm global prefix to ~/.local:

   npm config set prefix ~/.local

2. Install Claude Code via native installer (default install location: ~/.local/share/claude/versions/<version>/, with symlink ~/.local/bin/claude)
3. Run claude /doctor

Expected

/doctor should detect that ~/.local/bin/claude is a symlink to the native install (~/.local/share/claude/versions/<version>/) and not report it as a "Leftover npm global installation".

Actual

⚠ Multiple installations found
├ npm-global at /home/enos/.local/bin/claude
└ native at /home/enos/.local/bin/claude

⚠ Leftover npm global installation at /home/enos/.local/bin/claude
  └ Run: npm -g uninstall @anthropic-ai/claude-code

Both paths reported are the same path, and that path is a symlink to the native install:

$ file ~/.local/bin/claude
/home/enos/.local/bin/claude: symbolic link to /home/enos/.local/share/claude/versions/2.1.150

Running the recommended fix is a no-op because there is no npm package to remove:

$ npm -g uninstall @anthropic-ai/claude-code
up to date in 94ms

$ npm list -g --depth=0 | grep -i claude
# (empty — no claude package known to npm)

$ ls ~/.local/lib/node_modules/@anthropic-ai/ 2>&1
ls: cannot access '...': No such file or directory

The warning persists on subsequent /doctor runs.

Root cause hypothesis

The detection heuristic appears to check for a claude file/symlink at $(npm config get prefix)/bin/claude and assume any presence there is an npm-global installation. When the user's npm prefix is the same directory as the native install's bin symlink target (~/.local/bin is a common default for both), this heuristic fires incorrectly.

Suggested fix

/doctor should distinguish between:

1. Real npm-global install: package @anthropic-ai/claude-code actually present in $(npm root -g)
2. Path coincidence: a claude binary/symlink exists at $npm_prefix/bin/ but no corresponding npm package exists in node_modules

Check ~/.local/lib/node_modules/@anthropic-ai/claude-code/package.json (or equivalent via npm ls -g @anthropic-ai/claude-code --json) before reporting the warning. If the npm package isn't present, treat the binary as not-npm-installed.

Impact

Currently cosmetic only. Concern: if a future Claude Code release adds auto-remediation based on this detection (e.g., automatically removing the "leftover" binary), users with this configuration would lose their working native install. Filing now as preemptive mitigation.

Workaround

None functional. Users can either ignore the warning or relocate npm prefix elsewhere (e.g., npm config set prefix ~/.npm-global), which requires reinstalling any npm-global packages.