[BUG] `claude` command unavailable after npm auto-update until `hash -r` is run (shell hash table caching)

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report
• [x] I am using the latest version of Claude Code

What's Wrong?

When Claude Code auto-updates via npm on macOS/Linux, the claude command becomes temporarily unavailable in the current shell session. Running claude fails with "command not found" or returns the old version, even though the update completed successfully.

Root Cause: Shell hash table caching combined with npm symlink recreation.

When npm updates the package:

1. npm reinstalls package to /opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/
2. npm recreates symlink: /opt/homebrew/bin/claude → cli.js
3. The new symlink has a different inode than before
4. zsh/bash hash table still caches the old symlink's inode
5. Running claude fails until hash -r is executed to refresh the hash table

This is different from the Homebrew upgrade issue (#18019) because:

• The binary path doesn't change
• The symlink path doesn't change
• Only the symlink's inode changes, breaking the shell's internal cache

What Should Happen?

After auto-update completes, the claude command should work immediately in the same shell session without requiring hash -r.

Error Messages/Logs

# Before update
$ claude --version
2.1.16 (Claude Code)

# Claude auto-updates to 2.1.17

# Immediately after update in same shell
$ claude --version
zsh: command not found: claude

# OR old version is returned (stale cache hit)
$ claude --version
2.1.16 (Claude Code)

# After running hash -r
$ hash -r
$ claude --version
2.1.17 (Claude Code)

Steps to Reproduce

1. Install Claude Code via npm: npm install -g @anthropic-ai/claude-code
2. Open a terminal and run claude to start a session
3. Allow auto-update when prompted (or run claude update)
4. After update completes, in the same terminal, run claude --version
5. Observe that either:

• Command is not found
• Old version is displayed (stale cache)

1. Run hash -r to clear shell hash table
2. Run claude --version again - now shows correct new version

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Claude Code Version

2.1.17 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Proposed Fix

Add a hash -r (or equivalent) command after npm update operations complete. Options:

Option 1: Post-update message (minimal change)

After auto-update, display:

Update complete. Run `hash -r` or open a new terminal to use the updated version.

Option 2: Automatic shell rehash (better UX)

If the update process can detect it's running in an interactive shell, it could:

# For zsh/bash
hash -r 2>/dev/null || true

Option 3: Shell profile addition (recommended for native installer)

Add to shell profile during installation:

# Automatically rehash on completion (handles symlink changes)
zstyle ':completion:*' rehash true

Workarounds

Users can work around this issue by:

1. Run hash -r after any update
2. Open a new terminal after updates
3. Add to ~/.zshrc:

``zsh
zstyle ':completion:*' rehash true
``

1. Migrate to native installer (recommended, as npm is deprecated):

``bash
npm uninstall -g @anthropic-ai/claude-code
curl -fsSL https://claude.ai/install.sh | bash
``

Additional Information

This is a well-known issue with any npm global package that gets updated while the shell has cached its path. References:

• https://stackoverflow.com/questions/15691977/after-updating-npm-packages-hash-fails
• https://unix.stackexchange.com/questions/5609/how-do-i-clear-bashs-cache-of-paths-to-executables

The native installer may not have this issue because:

1. It installs to ~/.local/bin/claude (a stable path)
2. The update mechanism may differ from npm's symlink recreation
3. The binary itself is replaced in-place rather than via symlink

Note: Since npm installation is deprecated (per CHANGELOG v2.1.15 and README), this issue may be considered low priority. However, documenting the workaround in the troubleshooting docs would help affected users.