[BUG] Migration from npm leaves orphaned symlink that shadows native binary

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

After migrating from npm to native installation, the previous npm installation artifacts remain on the system and shadow the new native binary:

1. Orphaned symlink: /usr/bin/claude still exists, pointing to ../lib/node_modules/@anthropic-ai/claude-code/cli.js
2. Orphaned node_modules: /usr/lib/node_modules/@anthropic-ai/ directory remains
3. PATH conflict: The native binary installs to ~/.local/bin/claude, but /usr/bin comes before ~/.local/bin in most users' PATH

The result is that which claude returns /usr/bin/claude (the old npm symlink) instead of ~/.local/bin/claude (the new native binary). If the user subsequently removes npm, the symlink becomes broken but still shadows the native installation.

What Should Happen?

The native installer should either:

1. Detect and remove the old npm installation (symlink + node_modules directory), OR
2. Warn the user that a previous installation exists and provide manual cleanup instructions, OR
3. At minimum, clearly inform the user that ~/.local/bin must be in PATH before /usr/bin

Error Messages/Logs

$ which claude
/usr/bin/claude

$ file /usr/bin/claude
/usr/bin/claude: symbolic link to ../lib/node_modules/@anthropic-ai/claude-code/cli.js

$ ls -la ~/.local/bin/claude
lrwxrwxrwx 1 mod users 45 Jan 21 21:08 /home/mod/.local/bin/claude -> /home/mod/.local/share/claude/versions/2.1.15

$ ls /usr/lib/node_modules/@anthropic-ai/
claude-code

Steps to Reproduce

1. Install Claude Code via npm: sudo npm install -g @anthropic-ai/claude-code
2. Run the native installer: curl -fsSL https://claude.ai/install.sh | bash
3. Observe that /usr/bin/claude still exists and points to the old npm installation
4. Run which claude - returns /usr/bin/claude instead of ~/.local/bin/claude
5. (Optional) Remove npm with package manager - symlink becomes broken but still shadows native binary

Claude Code Version

2.1.15

Platform

Anthropic API

Operating System

Arch Linux (kernel 6.18.5-arch1-1)

Terminal/Shell

Bash

Manual Workaround

For users who encounter this issue:

# Remove old npm symlink
sudo rm /usr/bin/claude

# Remove orphaned node_modules (optional)
sudo rm -rf /usr/lib/node_modules/@anthropic-ai

# Ensure ~/.local/bin is in PATH (add to ~/.bashrc)
export PATH="$HOME/.local/bin:$PATH"

# Verify native installation
which claude  # Should show ~/.local/bin/claude
claude --version

Additional Context

The installation prompt that appears after running the native installer mentions adding ~/.local/bin to PATH, but it disappears quickly and doesn't mention the potential conflict with existing npm installations. The claude install migration command also does not clean up the previous installation.

Claude Model

Opus

Is this a regression?

I don't know

Last Working Version

_No response_

Claude Code Version

2.1.15

Platform

Anthropic API

Operating System

Other Linux

Terminal/Shell

Other

Additional Information

_No response_