[BUG] UI shows "update available" for latest-channel versions when installed from stable apt repo
Preflight Checklist
- [x] I have searched existing issues and this hasn't been reported yet
- [x] This is a single bug report (please file separate reports for different bugs)
- [x] I am using the latest version of Claude Code
What's Wrong?
When Claude Code is installed via the stable apt repository on Linux — which is what the official setup documentation (https://code.claude.com/docs/en/setup#install-with-linux-package-managers) instructs users to do — the in-app updater UI compares the installed version against the latest channel
by default. This causes the UI to show "update available" notifications for versions that cannot actually be installed via apt upgrade, because the stable apt repo hasn't published them yet.
The mismatch can only be fixed by manually adding "autoUpdatesChannel": "stable" to ~/.claude/settings.json, which most users don't know about. Since the official docs only describe the stable install path, every user following the documented setup is affected by this mismatch out of the box.
Why this matters
Users who follow the official Linux setup docs receive the stable build, but the UI then shows them latest-channel update prompts and tells them to "run update manager" for a version that the documented package source will not deliver. This:
- Undermines the user's deliberate choice of the stable channel
- Adds persistent UI noise that can't be dismissed without finding an undocumented setting
- Causes confusion when apt upgrade reports "nothing to do" despite the UI claiming an update is available
- Is undiscoverable to fix without reading the full settings schema
Environment
- OS: Ubuntu (Linux 6.8.0-124-generic)
- Installation method: .deb package from the official Anthropic apt repository, following the official Linux package manager setup guide (https://code.claude.com/docs/en/setup#install-with-linux-package-managers)
- APT source:
deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main - Installed version: claude-code 2.1.153-1 (stable channel)
- Reported by UI: Latest version: 2.1.170 (latest channel)
<img width="1060" height="275" alt="Image" src="https://github.com/user-attachments/assets/960bef4a-68b6-4e2b-a982-581d77ed5048" />
What Should Happen?
Expected behavior
If the package is installed from the stable apt repository (the path documented in the official setup guide), the in-app updater should compare against the stable release channel by default. The user should not see "update available" prompts for versions that the configured package source doesn't
actually distribute.
Actual behavior
The UI defaults autoUpdatesChannel to latest regardless of which apt repo the package came from, producing misleading update notifications and prompting the user to ""Run your package manager update command." for a version that won't appear there. Because the official docs only document the stable install path, this
affects every user who installs Claude Code via the supported Linux method.
Workaround
Manually add to ~/.claude/settings.json:
{
"autoUpdatesChannel": "stable"
} After this, the UI correctly compares against the stable channel and the false notification disappears.
Suggested fix
A few possible approaches:
- Package-side default: The .deb (and .rpm) postinst script could write a default "autoUpdatesChannel": "stable" to a managed-settings location at install time, since the package itself comes from the stable channel.
- Auto-detect from apt source: The in-app updater could read /etc/apt/sources.list.d/claude-code.list and pick the matching channel automatically.
- Documentation update: At minimum, the official setup guide (https://code.claude.com/docs/en/setup#install-with-linux-package-managers) should instruct users to also set autoUpdatesChannel: "stable" in ~/.claude/settings.json after installing from the stable repo.
The first two are preferable — the UI's update channel should align with the package source the user opted into without requiring undocumented manual configuration.
Error Messages/Logs
Steps to Reproduce
- Install Claude Code on Linux following the official documentation (https://code.claude.com/docs/en/setup#install-with-linux-package-managers), which points users to the stable channel:
sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
-o /etc/apt/keyrings/claude-code.asc
echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
| sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update
sudo apt install claude-code - Open Claude Code and check the version banner / status.
- Observe:
├ Stable version: 2.1.153
└ Latest version: 2.1.170
- The UI prompts: "Run your package manager update command."
<img width="1060" height="275" alt="Image" src="https://github.com/user-attachments/assets/960bef4a-68b6-4e2b-a982-581d77ed5048" />
- Run sudo apt update && sudo apt install --only-upgrade claude-code — no upgrade is available, because 2.1.170 is not in the stable apt channel.
Claude Model
Opus
Is this a regression?
I don't know
Last Working Version
_No response_
Claude Code Version
2.1.153
Platform
Anthropic API
Operating System
Ubuntu/Debian Linux
Terminal/Shell
IntelliJ IDEA terminal
Additional Information
_No response_