[FEATURE] Windows installer should add %USERPROFILE%\.local\bin to the User PATH itself

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

The native Windows installer puts claude.exe in %USERPROFILE%\.local\bin but never adds that folder to PATH. Checked against the raw registry rather than the shell: it is in neither HKCU\Environment nor the machine value, so it was never written.

claude doctor catches it and points the user at System Properties > Environment Variables > Edit User PATH > New.

That dialog is where it goes wrong. New appends a row, Edit changes the selected one, and if a row happens to be selected, New replaces it. No confirmation, no undo. Follow the instructions literally and you can end up with a User PATH containing .local\bin and nothing else, with whatever was there before gone. When the replaced row is %LOCALAPPDATA%\Microsoft\WindowsApps, winget goes with it. The dialog also flips the value type from REG_EXPAND_SZ to REG_SZ, which kills any %VAR% entry added later.

The System variables list sits in the same window, one box below the one doctor is sending people to, with an identical Edit dialog and nothing marking it as riskier. The same click there is machine wide: services and scheduled tasks resolve against the system value and never see the user one. The rows in that list are system32, %SystemRoot%, Wbem, WindowsPowerShell\v1.0 and OpenSSH.

The users most likely to click New instead of Edit are the ones least equipped to notice, or to get back. Nothing announces it. Commands just stop resolving.

Related: #80087, #85475, #68896.

Proposed Solution

Have the installer write %USERPROFILE%\.local\bin into the User PATH. HKCU needs no admin, so nothing blocks it.

Four things that bite if you do:

• setx truncates at 1024 chars and flattens REG_EXPAND_SZ to REG_SZ. Write HKCU\Environment directly.
• Read the existing value with DoNotExpandEnvironmentNames, or every %VAR% in it gets baked into an absolute path.
• Upgrade REG_SZ to REG_EXPAND_SZ when the new value contains a %, since the dialog leaves plenty of PATHs as REG_SZ.
• Broadcast WM_SETTINGCHANGE, or nothing sees the change until sign out and the user assumes it failed.

I hit all four building a repair tool for this. Single .cmd, no install, MIT, if it is useful as a reference: https://github.com/AbdulrahmanAmer/path-doctor

If writing PATH at install time is off the table, claude doctor offering to do it is still better than pointing at that dialog.

Alternative Solutions

Documenting the New vs Edit trap helps people who read docs, and does not undo the click. claude doctor --fix needs the user to know to run it. Both are weaker than just doing it at install.

Priority

High - Significant impact on productivity

Feature Category

Other

Additional Context

Windows 11 Pro 25H2, build 26200.8875, native install, Claude Code 2.1.228, Windows PowerShell 5.1.

Happy to open a PR if the installer source is reachable. I could not find it in this repo.