[DOCS] Homebrew install/update docs omit stable vs latest cask channels
Documentation Type
Incorrect/outdated documentation
Documentation Location
https://code.claude.com/docs/en/setup
Section/Topic
Homebrew install tab and the Update Claude Code section
Current Documentation
The setup page currently says:
brew install --cask claude-codeHomebrew installations do not auto-update. Runbrew upgrade claude-codeperiodically to get the latest features and security fixes. Homebrew and WinGet installations do not auto-update. Usebrew upgrade claude-codeorwinget upgrade Anthropic.ClaudeCodeto update manually.
The same page explains release channels only for the native installer:
The native installer accepts either a specific version number or a release channel (latestorstable). The channel you choose at install time becomes your default for auto-updates.
No current code.claude.com page mentions claude-code@latest.
What's Wrong or Missing?
Changelog v2.1.92 says:
Fixed Homebrew install update prompts to use the cask's release channel (claude-code→ stable,claude-code@latest→ latest)
Current docs still present Homebrew as a single-cask install path and always tell users to update with brew upgrade claude-code.
That leaves the Homebrew guidance incomplete and partially outdated:
- it does not explain that Homebrew release-channel choice is cask-based
- it does not say that
claude-codetracks the stable channel - it does not document
claude-code@latestfor users who want the latest channel - it tells Homebrew users to run a single upgrade command even though v2.1.92 now distinguishes the correct update prompt by installed cask
Suggested Improvement
Update the Homebrew install/update docs to document the cask-specific release channels and the matching upgrade commands.
For example, clarify that:
brew install --cask claude-codefollows the stable channelbrew install --cask claude-code@latestfollows the latest channelbrew upgrade claude-codeandbrew upgrade claude-code@latestshould match the cask the user installed
The duplicated Homebrew snippets in quickstart, overview, troubleshooting, terminal-guide, and plugin troubleshooting should either be updated to reflect the same distinction or link back to a single canonical explanation on the setup page.
Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/setup | 71, 75, 171 | Primary Homebrew install and manual update guidance |
| https://code.claude.com/docs/en/quickstart | 475, 667, 671 | Install configurator and Homebrew install/update copy |
| https://code.claude.com/docs/en/overview | 52, 56 | Homebrew install snippet and update guidance |
| https://code.claude.com/docs/en/discover-plugins | 403 | Homebrew update instructions in /plugin troubleshooting |
| https://code.claude.com/docs/en/terminal-guide | 221 | Homebrew fallback install command |
| https://code.claude.com/docs/en/troubleshooting | 249, 290 | Alternative Homebrew install instructions |
Total scope: 6 pages affected
No current code.claude.com page mentions claude-code@latest.
Source: Changelog v2.1.92
Changelog entry:
Fixed Homebrew install update prompts to use the cask's release channel (claude-code→ stable,claude-code@latest→ latest)
3 Comments
References of this from Homebrew side :
homebrew-cask PR #255221 – PR that introduced the two-cask split
Homebrew Formulae – claude-code
Homebrew Formulae – claude-code@latest
Issue #43366 Verification
Title: [DOCS] Homebrew install/update docs omit stable vs latest cask channels
Issue Date: 2026-04-04
Verification Date: 2026-05-01
Status: RESOLVED
---
Issue Summary
This issue reports that the Homebrew install/update documentation was incomplete and partially outdated. Specifically, it claimed that:
code.claude.compage mentionedclaude-code@latestclaude-codetracks stable andclaude-code@latesttracks latestbrew upgrade claude-codecommandThe reporter requested that the Homebrew install/update docs be updated to document the cask-specific release channels and matching upgrade commands across six affected pages.
---
Verification Results
Claim 1:
claude-code@latestis not documented anywhere on code.claude.comStatus: RESOLVED
At https://code.claude.com/docs/en/setup, line 74:
The same language appears at https://code.claude.com/docs/en/overview, line 689 and https://code.claude.com/docs/en/quickstart, line 586.
---
Claim 2: Docs do not explain that Homebrew release-channel choice is cask-based
Status: RESOLVED
At https://code.claude.com/docs/en/setup, line 74, the documentation explicitly states:
At line 209, the setup page further clarifies:
---
Claim 3: Update instructions only mention single
brew upgrade claude-codecommandStatus: RESOLVED
At https://code.claude.com/docs/en/setup, line 77:
The same dual-command guidance appears at https://code.claude.com/docs/en/overview, line 692, and https://code.claude.com/docs/en/quickstart, line 589.
At https://code.claude.com/docs/en/discover-plugins, line 411:
---
Current State
| Claim | Status |
|-------|--------|
|
claude-code@latestnot documented | RESOLVED || Homebrew channel choice not explained as cask-based | RESOLVED |
| Update instructions only mentioned single command | RESOLVED |
---
Suggested Fix
N/A - issue has been resolved.
---
References
---
Conclusion & Recommendation
Primary Concern: Homebrew install/update docs omitted the stable vs latest cask channels, making it unclear how Homebrew users should handle updates.
Resolution Status: RESOLVED
Recommendation: CLOSE
The documentation has been updated to fully explain the two Homebrew cask channels (
claude-codefor stable,claude-code@latestfor latest) and the corresponding upgrade commands. All six affected pages identified in the issue now contain the corrected documentation.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.