Summary

Claude Code's own installer places the binary in ~/.local/bin. However, the shell snapshot mechanism writes a hardcoded export PATH=... at the end of the snapshot file that is sourced for every Bash tool invocation. This snapshot PATH is derived from the launch-time process environment — not from the user's shell config — so user-level PATH additions (including ~/.local/bin) are silently dropped.

The result: Claude Code warns at every startup that ~/.local/bin is not in PATH, even though the user is successfully running the binary that lives there.

Steps to reproduce

1. Install Claude Code via the native installer (places binary in ~/.local/bin)
2. Add ~/.local/bin to PATH in ~/.zshrc or ~/.zshenv (as the warning suggests)
3. Restart Claude Code
4. Warning persists — inspect ~/.claude/shell-snapshots/*.sh and note the final export PATH=... line does not include ~/.local/bin

Root cause

~/.claude/shell-snapshots/*.sh ends with a hardcoded export PATH= line appended by Claude Code after shell capture. This line overwrites the PATH set by the user's shell config (~/.zshrc, ~/.zshenv, ~/.zprofile). Only paths present in /etc/paths or /etc/paths.d/ (macOS system-level) survive, because path_helper runs before any user shell config.

Impact

• Users are told to fix their ~/.zshrc — but fixing it has no effect
• The only working fix is a system-wide sudo tee /etc/paths.d/local-bin — an elevated change that should never be required for a user-space tool
• Every restart shows the warning, eroding trust in the install

Expected behavior

Either:

1. The snapshot PATH generation should include ~/.local/bin when the installer placed the binary there, or
2. The startup warning should be suppressed if the binary was successfully found and launched (i.e., it IS reachable via the user's PATH, just not via the snapshot PATH)

Environment

• macOS 15.4 (Darwin 25.4.0)
• Shell: zsh
• Claude Code v2.1.91
• Related: [DOCS] Bash tool docs missing login-shell default behavior change and CLAUDE_BASH_NO_LOGIN context #28043, [DOCS] Guide: direnv (+ devbox) environment loading via hooks #42229