[DOCS] No docs note Claude installed with Homebrew will silently install another instance in ~/.local/share/claude/versions/

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/quickstart#homebrew

Section/Topic

Getting Started > Quickstart > Step 1: Install Claude Code > Homebrew

Current Documentation

Claude Code's documentation states in "Getting Started > Quickstart > Step 1: Install Claude Code > Homebrew" in an admonition block:

Homebrew installations do not auto-update. Run brew upgrade claude-code or brew upgrade claude-code@latest, depending on which cask you installed, to get the latest features and security fixes.

What's Wrong or Missing?

What's wrong is a serious trust issue: at some point, the Claude Code instance I installed via Homebrew appears to have installed another, independent instance of itself in a different location without any prompt or action from me. This behavior is neither documented in the project's changelog nor is it documented in the web documentation. Furthermore, that independent instance of itself _does_ self-update, like the native installer, which was unexpected because I didn't realize a new instance had been installed, and because the existing instance I installed _does not_ self-update.

It appears as though sometime around the release of version 2.1.223, possibly earlier, the claude binary installed via brew install --cask claude-code@latest installed another, separate instance of itself in ~/.local/share/claude/versions/${VERSION}, symlinked to ~/.local/bin/claude, where ${VERSION} was 2.1.223. This binary subsequently self-updated, and as far as I can tell, keeps the last 3 versions it has downloaded: currently 2.1.224, 2.1.226, and 2.1.227, as of writing this bug report (around 2026-08-11T10:00-07:00).

Looking at ~/.claude.json reveals two key-value pairs potentially relevant to this behavior:

{
    "autoUpdates": false,
    "autoUpdatesProtectedForNative": true
}

While I don't know exactly what those keys are supposed to control, the autoUpdatesProtectedForNative key suggests to me this auto-migration might be intended behavior.

I've searched my own command history for the past year and I don't see any claude install command that would have caused this behavior to occur, nor did I use the curl-based native installer. I've also searched my Claude Code logs for the past 3 months and don't see any prompts or tool calls to suggest Claude ran its native installer due to prompts from me.

While it is technically true that the Claude instance I installed via Homebrew does not itself auto-update, without any notification from Claude that I was migrated to a native install, all I saw was an updated version of Claude, and only after another tool on my system notified me I had more than one copy of Claude installed. Without knowledge of the new Claude instance, it would appear as though the Claude instance I thought I was using -- the one from Homebrew with auto-updates disabled -- was auto-updating.

Finally, it's worth noting that as a result of the migration, the two installations on my machine update independently. Claude is still listed as installed in Homebrew and updates upon brew upgrade, while the Claude in ~/.local/share/claude/version/ auto-updates on its own pace. This behavior is confusing. The quickstart docs seem to suggest that the native installer is merely "recommended" when this auto-migration would suggest that the Claude Code project has gone further -- possibly deprecating the Homebrew installation method for later removal.

Suggested Improvement

At minimum, the project changelog should note, if accurate:

• The auto-migration behavior from Homebrew to the native installer.
• This migration will mean that the new Homebrew instance auto-updates (as if installed by the native installer).
• Note the autoUpdates and autoUpdatesProtectedForNative keys and what they do.

Claude should also print a message that it's doing this migration so I don't have to find out from some other tool that it has already occurred.

If the intention is to continue to support installation via Homebrew indefinitely, then it would be better for Claude to prompt as to whether I actually want to do this migration, and to provide means to disable this migration. If there is a means to disable this migration via an environment variable, it would be preferable for that environment variable to be appropriately namespaced, e.g., CLAUDE_CODE_DISABLE_UPDATES, to reduce the possibility of environment variable collisions with other software. If the intention is _not_ to support installation via Homebrew indefinitely, it would be preferable to deprecate the Homebrew cask and to note in the quickstart docs that the Homebrew installation method is deprecated.

I'd also suggest some messaging about why the project is making this change. I can appreciate wanting to get updates into users' hands as quickly as possible, including access to new models and access to security fixes. However, it's a huge breach of trust to find out that the installation method a user has chosen has silently been migrated to a different method. Claude performed a write operation I did not authorize and one that I would have prevented had I been prompted about it. This instance isn't the first time I've discovered Claude doing something it theoretically wasn't supposed to do, and suggests the existing Claude-native sandboxing mechanisms are not something I or other users should trust.

Impact

Medium - Makes feature difficult to understand

Additional Context

As noted above, it's a trust issue. The software violates the expected design contract of installation via a package manager and installed another copy of itself without my approval and without any notification indicating it had done so. It leaves me wondering what else I could find that Claude has done without my approval.