[DOCS] Installation docs do not explain externally managed launcher protection

Status Fixed / completed

Maintainer reply ✓ Yes — bcherny

Activity 3 comments · opened Jul 11, 2026 · closed Aug 17, 2026

💡 Likely answer: A maintainer (bcherny, collaborator) responded on this thread — see the highlighted reply below.

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/setup

Section/Topic

The “Auto-updates” section and the installation/troubleshooting guidance for users who place Claude Code behind a custom launcher or symlink.

Current Documentation

The setup page currently says:

“Claude Code checks for updates on startup and periodically while running. Updates download and install in the background, then take effect the next time you start Claude Code.”

It also says:

“Run claude doctor to see the result of the most recent update attempt.”

The documentation describes an npm global directory that is not writable, but does not describe a custom launcher script or symlink at ~/.local/bin/claude.

What's Wrong or Missing?

Claude Code v2.1.207 fixed the updater so it no longer overwrites a custom launcher script or symlink at ~/.local/bin/claude, and /doctor now reports when the launcher is externally managed. This is a user-visible installation and update behavior, but the setup and troubleshooting pages do not explain it.

Users who manage Claude Code through a wrapper, symlink, or organization-owned launcher have no documented way to understand why the launcher is preserved, what /doctor reports, or which underlying installation they must update themselves.

Suggested Improvement

Add an “Externally managed launchers” note to the update section. Explain that a script or symlink at ~/.local/bin/claude is preserved by the Claude Code updater, that /doctor reports the launcher as externally managed, and that the user should update the underlying Claude Code installation through the tool that owns the launcher.

Include the corresponding diagnostic in the /doctor command reference or troubleshooting page, with a short example of how to inspect the resolved launcher target without implying that Claude Code should replace it.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/setup | Auto-update behavior and claude doctor update diagnostics |
| https://code.claude.com/docs/en/commands | /doctor command reference does not mention externally managed launchers |
| https://code.claude.com/docs/en/troubleshooting | General /doctor and installation troubleshooting entry point |

Total scope: 3 pages affected

Source: Claude Code v2.1.207

Fixed the auto-updater overwriting a custom launcher script or symlink at ~/.local/bin/claude on every release; /doctor now reports an externally managed launcher

View original on GitHub ↗

3 Comments

SankeerthNara · 3 months ago

Could you assign this to me

bcherny collaborator · 1 month ago

The setup docs now cover this. The auto-update section explains that if you replace ~/.local/bin/claude with your own script or symlink, auto-update and claude update leave it in place (new versions still install under ~/.local/share/claude/versions/), that claude doctor reports a launcher the installer didn't create, that all installed versions are kept on disk in that case, and how to let Claude Code manage the launcher again. See https://code.claude.com/docs/en/setup and the changelog at https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md.

Closing as documented.

🤖 Generated with Claude Code

github-actions[bot] · 8 days ago

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.