claude-code - 💡(How to fix) Fix [DOCS] Windows updater docs omit `claude.exe` in-use recovery guidance

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

Update Claude Code -> Auto-updates and Update manually, especially Windows update failures when the installed claude.exe is still in use.

Current Documentation

The update docs explain the normal native update path:

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.

They also say where to inspect update status:

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

The same section documents a Windows executable-lock case only for WinGet package-manager auto-update:

On WinGet the upgrade may fail while Claude Code is running because Windows locks the executable. In that case Claude Code shows the manual command instead.

The install troubleshooting page documents a different Windows file-in-use failure during installer download:

If the PowerShell installer fails with Failed to download binary: The process cannot access the file ... because it is being used by another process, the installer couldn't write to %USERPROFILE%\.claude\downloads. This usually means a previous install attempt is still running, or antivirus software is scanning a partially downloaded binary in that folder.

What's Wrong or Missing?

A. Native Windows update failures caused by claude.exe being in use are not documented

The setup page documents background auto-updates and claude update, but it does not explain what Windows users should do when the installed %USERPROFILE%\.local\bin\claude.exe is locked by another Claude Code session or process.

B. Existing Windows lock guidance points to the wrong recovery path

The only update-related executable-lock note is specific to WinGet and says Claude Code shows the manual command instead. The install troubleshooting page covers a download-folder lock under %USERPROFILE%\.claude\downloads, not the installed claude.exe being locked during update.

C. Users need the new actionable error behavior reflected in docs

The v2.1.154 changelog says Windows update failures caused by claude.exe being in use now tell users to close other sessions and retry instead of showing a generic error. The docs should mirror that recovery instruction so users can understand the failure and act on it even when reading the setup or troubleshooting pages first.

Suggested Improvement

Add a Windows note under Auto-updates or Update manually, and cross-link it from install troubleshooting.

Suggested wording:

On Windows, updates can fail if another Claude Code session or process is still using claude.exe. If Claude Code reports that claude.exe is in use, close other Claude Code terminal sessions, background/agent sessions, IDE sessions, or desktop app sessions that may be running the CLI, then retry claude update. Run claude doctor to confirm the most recent update attempt.

If the behavior differs between native installs, WinGet installs, and npm installs, document those differences in the same update section.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Version context: v2.1.154 changelog entry: Windows fixed update failures caused by claude.exe being in use showing a generic error instead of telling users to close other sessions and retry.