aaddrick--claude-desktop-debian/docs/decisions.md

< Back to README

Decision Log

This log captures direction-level decisions that shape what this project does and — just as importantly — what it explicitly does not do. Each entry records the decision, the rationale at the time it was made, and the trade-offs accepted.

Decisions are not deleted. If a decision is revisited, the entry is marked Superseded and a new entry links back to it. This preserves the reasoning so future contributors don't have to relitigate settled questions without context.

Format. Each decision has a stable ID (D-NNN), a status, a decision date, an owner, and a short list of affected stakeholders. Decisions do not need to be long — they need to be clear about what was chosen and what was refused.

Adding a new decision. Append a new H2 section with the next D-NNN ID, add a row to the index, and keep the entry tightly scoped to one direction call. If a decision touches multiple areas, split it.

Revisiting a decision. Open an issue that cites the decision ID and describes what's materially changed since the original call. Don't open a PR that violates a recorded decision without first getting the decision reopened.

Index

ID	Date	Status	Title
D-001	2026-04-21	Accepted	Auto-update stays in the package-manager lane
D-002	2026-07-02	Accepted	Rebase onto the official Linux .deb, patch-zero

---

D-001 — Auto-update stays in the package-manager lane

• Status: Accepted
• Decided: 2026-04-21
• Owner: @aaddrick
• Stakeholders: Users on deb / rpm / AUR; AppImage users; external contributors proposing auto-update features

Context

A contributor submitted a proposal (PR #320) that added roughly 550 lines of nightly cron-driven update scripts covering both Claude Desktop (rebuild-and-reinstall from source) and the Claude Code CLI (via claude update). The same PR contained an unrelated fix for GPU compositing on XRDP sessions (#319).

The XRDP portion was salvaged into PR #475 and merged. This entry records why the auto-update portion was declined at the direction level — not as a rework request, but as a "this is not a shape we'll ship."

Decision

This project does not ship an in-tree auto-updater. Updates are delivered exclusively through:

1. The APT repository for Debian and Ubuntu users
2. The DNF repository for Fedora and RHEL users
3. The AUR package for Arch users
4. AppImageUpdate / embedded zsync info as the sanctioned direction if and when AppImage auto-update is prioritized

No cron-driven, systemd-timer-driven, or in-app rebuild-and-reinstall flows will be merged.

Rationale

• The platforms that matter already have the right answer. Users on distributions where this project publishes a package repository get updates through their OS's package manager. That's the correct shape: the OS's update stack is the thing users configure, audit, and trust. Standing up a parallel path inside this project fragments the experience and duplicates machinery that already works.
• The DE-neutral answer for AppImage is AppImageUpdate, not a bespoke updater. A parallel AppImage update path would mean owning process detection, session-aware safety checks, and sudo escalation across every desktop environment, session manager, notification system, and sandboxing model (Flatpak, Snap, Wayland, X11, systemd-inhibit, screen locks). AppImage already has a sanctioned update mechanism; if we ever close that gap, we close it by embedding zsync info in the release artifact.
• Security surface. An unattended updater running from cron with broad apt install privileges in a user's git clone is a large ambient capability for the project to own. APT pre-invoke hooks and .deb maintainer scripts mean that NOPASSWD: /usr/bin/apt install * is effectively passwordless root for anyone who can place a file on disk — a surface that does not exist when the user runs apt upgrade through the OS's package manager directly.
• Upstream parity. The Windows and Mac builds of Claude Desktop do not auto-update via cron. They use platform-native mechanisms. A Linux-specific cron updater would make this project's update behavior diverge from the expectations users carry in from the upstream product.
• Maintenance tail. Every session manager, notification system, sandboxing runtime, and "is the user actively using the app" heuristic becomes this project's problem to keep working across distros, indefinitely. The blast radius of a broken updater is "the app stops working cleanly for a fraction of users until they figure out how to intervene" — and we would own that 24/7.

Consequences

• Accepted trade-off. AppImage users who do not install from a supported distro's repo have no first-party auto-update path. Their options are: re-download the AppImage manually, use AppImageLauncher or Gear Lever, or switch to a supported package format.
• Future work. If AppImage auto-update becomes a priority, the sanctioned path is integrating zsync metadata into the release artifact and documenting AppImageUpdate usage — not a new cron script.
• Contributor guidance. PRs proposing in-tree auto-update mechanisms should reference this decision and are expected to be declined by default. Requests to reopen should be filed as issues that cite D-001 and describe what's materially changed — e.g., AppImage becomes the dominant distribution channel for this project, upstream changes its update strategy, or the package repos stop being viable.

Alternatives Considered

• Cron-driven auto-updater (the PR #320 shape). Rejected — rationale above.
• Systemd-timer variant of the same. Same concerns; the scheduling mechanism is not the hard part.
• Watch-mode "update when idle" daemon. Worse on balance — owning an always-on daemon that decides when the user is "idle enough" for an update is a larger maintenance surface than the cron approach and carries the same security footprint.
• AppImageUpdate / zsync integration. Accepted as the sanctioned direction if AppImage auto-update is ever prioritized. Not implemented today; recorded here so future contributors know which direction is open.

References

• PR #320 — original auto-update proposal (closed, superseded by PR #475 for the salvageable XRDP portion): https://github.com/aaddrick/claude-desktop-debian/pull/320
• PR #475 — XRDP fix salvaged from PR #320: https://github.com/aaddrick/claude-desktop-debian/pull/475
• Issue #319 — the XRDP bug that motivated PR #320: https://github.com/aaddrick/claude-desktop-debian/issues/319
• Close comment on PR #320 articulating the direction: https://github.com/aaddrick/claude-desktop-debian/pull/320#issuecomment-4288390494

---

D-002 — Rebase onto the official Linux .deb, patch-zero

• Status: Accepted
• Decided: 2026-07-02
• Owner: @aaddrick
• Stakeholders: All users; @typedrat (Nix); @RayCharlizard (Cowork); @sabiut (tests); external contributors proposing patches

Context

Anthropic shipped a first-party Claude Desktop for Linux beta on 2026-06-30 (1.17377.1, Electron 42.5.1) via an APT repository. The teardown (report CDL-ANT-0008) verified it natively solves most of what this project's patch suite existed to fix — tray SNI race, frameless window, autoUpdater, native-binding stub, node-pty — and adds capability a Windows repackage cannot reproduce (KVM Cowork VM, Rust X11 input injection, browser native-messaging host). Continuing to repackage the Windows installer would mean maintaining a worse-behaved fork of the same app.

Decision

v3.0.0 repackages Anthropic's official Linux .deb instead of the Windows installer, in one hard cutover. The Windows pipeline and every patch that is redundant against official bytes were deleted in a single arc (fallback: git history and the pre-cutover-windows-pipeline tag).

Sub-decisions:

1. Patch-zero is the contract. Every asar patch must justify itself against official bytes; the default verdict is delete. With an empty active_patches array the official app.asar ships byte-identical. Survivors as of the cutover: quick-window (KDE stale-focus, pending the QW-1 repro) and org-plugins (upstream has no linux case — filed upstream). Evidence: docs/learnings/official-deb-rebase-verification.md and report CDL-ANT-0009.
2. Launcher policy is opt-in only. No default launcher flag may shadow an official code path; tools/chromium-switch-smoke.sh fails CI on switch-list drift. --password-store auto-detection was dropped for the same reason (explicit CLAUDE_PASSWORD_STORE passthrough stays).
3. Cowork is KVM-only in 3.0.0, gated by doctor checks and honest messaging. The bwrap fallback is parked unwired (scripts/cowork-fallback/) as a separate 3.1 investigation behind a binary dispatcher (owner @RayCharlizard) — impersonating coworkd's undocumented socket protocol is off the 3.0.0 critical path.
4. Our .deb survives, renamed (claude-desktop-unofficial, distinct install/AppArmor paths; AppStream ID frozen). Amended 2026-07-04: the rename ships with v3.0.0 itself rather than as a separate v2.1.0 buffer release — main's pipeline is broken against upstream ≥ 1.17377.2, so an interim legacy release would only delay the fix. The conflict metadata is version-scoped (Conflicts:/Replaces: claude-desktop (<< 1.16000), rpm Obsoletes: claude-desktop < 1.16000): our legacy packages versioned ≤ 1.15200.x get cleanly swapped on upgrade, while Anthropic's official package (≥ 1.17377.1) is never matched — the two install side-by-side. They still share ~/.config/Claude and its SingletonLock, so coexistence is install-level, not run-level.
5. deb end-of-life condition: when Anthropic's APT channel flips live for general availability, re-evaluate our deb — thin launcher add-on (Depends: claude-desktop) or sunset. Until then we add value on every format (launcher, doctor, RPM/AppImage/Nix/AUR coverage).

Rationale

• The official build is the same app, built by the vendor, with Linux-native fixes we previously reverse-engineered — every patch we keep is a liability against fast upstream re-minification (the pool shipped three releases in the branch's first week).
• Formats Anthropic doesn't serve (RPM, AppImage, Nix, AUR) plus the launcher/doctor remain genuine value; a Windows repackage was not.
• A hard cutover beats a dual pipeline: the patch matrix was verified byte-by-byte against pristine official bundles, and live-hardware verification (FF-1, WCO-1, LD-1, CF-1) settled the deletions the bytes couldn't.

Consequences

• BREAKING launcher-surface changes recorded in the v3.0.0 CHANGELOG entry (titlebar/menu-bar/keep-awake/quit-on-close env vars gone, password-store explicit-only, glibc ≥ 2.34 for Cowork helpers).
• The Nix derivation was reworked onto the official tree in the same arc (ACQ-1, best-attempt draft): build-verified on x86_64, with runtime/aarch64 validation and the final shape owned by @typedrat.
• Upstream behavior we depend on is tripwired at build time (apt_channel_pending, menuBarEnabled:!0) instead of patched.
• Redistribution posture: the official copyright is License: Proprietary with no grant; mirroring consumed .debs into our releases is insurance, and the redistribution question goes to Anthropic before the new org name is public (user action).

Alternatives Considered

• Stay on the Windows repackage. Rejected — permanently worse app (no KVM Cowork, no Rust native binding), same patch-rot treadmill.
• Dual pipeline (Windows + official). Rejected — double CI, double patch matrix, no user benefit.
• Patch the official tree liberally. Rejected — patch-zero with per-patch justification is the point; see sub-decision 1.
• Ship the bwrap Cowork fallback in 3.0.0. Rejected — protocol-impersonation risk; descoped to 3.1 (sub-decision 3).

References

• Teardown: report CDL-ANT-0008 (official Linux .deb teardown)
• Patch-necessity matrix: docs/learnings/official-deb-rebase-verification.md; history: report CDL-ANT-0009
• D-001 — the official updater's apt_channel_pending early-return keeps updates in the package-manager lane, so D-001 stands unchanged