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

Documentation

Linux packaging, patching, and operations docs for the Claude Desktop for Debian project. The README is the storefront; this is the manual.

# If you're here because something broke:
claude-desktop-unofficial --doctor
# Then check troubleshooting.md below.

Installation & building

• Building from source — ./build.sh, format flags, how the official .deb is pinned and extracted
• Configuration — MCP config file locations, env vars, where state lives
• Troubleshooting — symptom-keyed fixes, --doctor warning index

Project direction

• Decision log — ADR-format record of what we ship and (more importantly) what we won't
• Releasing — pre-release checklist, tag recipe, what CI does on tag push
• Changelog — v2.0.0 onward, grouped by REPO_VERSION

How the patches work — subsystem deep-dives

Hard-won knowledge from debugging real bugs. Consult before working on the related subsystem; add a new entry when you discover something non-obvious that would save the next contributor (human or AI) significant time.

• Official-deb rebase verification — patch-necessity matrix against the official Linux .deb, the install-layout facts the v3.0.0 rebase depends on, and the live pre-ship open-items checklist
• Patching minified JavaScript — anchor selection, the \w vs $ capture trap, beautified false-negatives, idempotency guards; still load-bearing for the two survivor patches
• Cross-build: host vs target — tools that run during the build key on uname -m, artifacts key on --arch; the Exec format error class caught twice in the CI cutover
• Packaging permissions — restrictive-umask traps across deb/rpm/AppImage (app.asar.unpacked traversability, --root-owner-group, the rpm %defattr file-mode trap)
• APT/DNF Worker architecture — Cloudflare Worker + GitHub Releases redirect chain, credential ownership, heartbeat runbook
• Nix packaging — the official-deb derivation design contract, the live SRI auto-bump sed anchors, why the resource-path hack must not return, testing without NixOS
• Wayland GlobalShortcuts portal — why Quick Entry's hotkey is focus-bound on GNOME Wayland and the CLAUDE_USE_WAYLAND tri-state
• Tray rebuild race — KDE SNI re-registration race; validated — the official build converged on the same in-place fix
• Plugin install flow — Anthropic & Partners plugin gate logic and DevTools recipes
• Cowork VM daemon — the 2.x bwrap daemon; superseded on KVM hosts, reference for the 3.1 fallback investigation
• MCP double-spawn — why stdio MCPs spawn twice with chat + Code/Agent panels open
• Test harness — Electron hooks — why constructor-level BrowserWindow wraps were bypassed by the (now-deleted) frame-fix Proxy; the prototype-hook pattern that remains correct
• Test harness — AX-tree walker — five non-obvious traps in the v7 fingerprint walker
• Test methodology and coverage — how a green run is kept honest: the half-pinned-test failure class (run-subshell mutation loss, near-miss anchors, mirror stubs, false-green PASS), host-state isolation, launch-smoke reaping, and the mutation-check review discipline
• Config-wipe recovery — the poisoned-cache claude_desktop_config.json wipe, the renderer's grouping-state storage chain, the launcher-side backup rotation that recovers it (patch-zero-clean), and why the in-band asar guard is parked
• Quit-cleanup scope fence — the two systemd-scope namespaces (KDE/GNOME KProcessRunner desktop-id scope vs Electron's own StartTransientUnit app-id self-scope), why the app-id is versioned and must be derived at runtime, why the self-scope still can't fence the terminal-launch helpers, and the finding that nothing orphans on clean quit or crash — so the #709 MCP-matching slice still has no survivor to reap

Testing

• Testing overview — what we test and how it's organized
• Test runbook — running tests locally
• Test matrix — what runs on what distro / format
• Test automation — CI workflow shape
• Quick-entry closeout — the Quick Entry test runner

Operations

• Issue triage bot — how the GitHub Actions issue-triage workflow works
• Upstream bug reports — the pending pile: drafts and filing status for bugs that belong upstream (Anthropic or Electron)

Style guides

• Bash style guide — the project's shell-script conventions (forked from YSAP)
• Docs style guide — how to write and organize docs (start here if you're adding a page)

Contributing

• CONTRIBUTING.md — what we accept, what goes upstream, AI-attribution policy
• CLAUDE.md — instructions for AI coding assistants (and a useful project archaeology read for humans)
• AGENTS.md — vendor-neutral mirror of CLAUDE.md for non-Claude AI tools
• SECURITY.md — private vulnerability reporting

Archive

Docs whose subject no longer ships, kept with an obsolescence header because the diagnosis work is still worth reading.

• Linux topbar shim — the four topbar gates and the WCO/implicit-drag-region investigation; the shim was deleted in v3.0.0 (official builds render the topbar on Linux), and its three Electron bugs moved to upstream-reports/
• Cowork-Linux handover — record of the original patch-based cowork Linux work, superseded by the official KVM path; the bwrap daemon is parked under scripts/cowork-fallback/