| name | architecture |
| description | Explains the purpose, features, and architecture of claude-desktop-bin - which repackages Anthropic's official Claude Desktop Linux .deb for Arch/Fedora/RHEL/Nix/AppImage and layers Linux-only extras (Computer Use, themes, multi-profile, Quick Entry) on top via surgical JS patches. Use when onboarding, writing docs/READMEs, explaining what the project does, or reasoning about how the official build and our patches fit together. |
| when_to_use | When the user asks what the project does, how the pieces fit, what we add on top of the official build, the USPs, or wants an architecture/overview explanation for docs or a new contributor. |
Architecture - claude-desktop-bin
Repackages Anthropic's official Claude Desktop Linux .deb for the distros Anthropic does not ship (Arch/AUR, Fedora/RHEL, NixOS, AppImage) and for our own Debian/Ubuntu .deb, while layering a small set of Linux-only value-adds that the official build does not provide. See /linux for compat specifics.
What we start from: the official Linux .deb
Anthropic publishes an official Claude Desktop build for Linux as a .deb in an apt repo (https://downloads.claude.ai/claude-desktop/apt). It bundles its own Electron (42.5.1) and ships a native Cowork VM backend (cowork-linux-helper + virtiofsd + smol-bin + QEMU/OVMF; requires /dev/kvm). The official build natively supports Chat, Code, Cowork, Computer Use is in beta upstream, and reads managed config from /etc/claude-desktop/managed-settings.json. We do not patch the Windows MSIX any more - that pipeline is gone.
What this repo does: ingest -> patch -> repackage
Ingest: download the official .deb (apt repo, or --deb PATH/--version X) -> verify GPG + SHA256 -> dpkg-deb -x -> locate usr/lib/claude-desktop/resources/app.asar -> asar extract.
Patch: run scripts/apply_patches.py (the orchestrator) over the extracted bundle. 48 surgical JS patches (patches/*.nim, compiled native binaries, regex on minified JS) apply Linux-only fixes and our value-adds. The official build re-minifies between releases, so patterns use [\w$]+ wildcards anchored on stable strings (feature names, log messages, process.platform==="darwin"), count EXPECTED_PATCHES, and quit(1) on any miss. .upstream-version records the last validated version.
Repackage: asar pack (preserving app.asar.unpacked, which carries the official build's pre-built native modules - we no longer rebuild node-pty) into a tarball, then build AUR/our-own-deb/rpm/AppImage/Nix from it.
Several patches that used to enable Cowork on Linux (the "cowork-wiring" cluster) were removed once the official build started shipping Cowork natively; what remains of that area is a small number of regression guards that assert the upstreamed native-Linux behavior is still present and fail loud if Anthropic ever drops it.
Value-adds we layer on top (the reason this repo exists)
- Computer Use - desktop automation (screenshot/click/type/scroll); session-aware backends (
fix_computer_use_linux + bundled kwin-portal-bridge). Our exclusive feature - not in the official Linux beta. See /linux for the input/screenshot cascades.
- Custom themes - dual light/dark built-in palettes (
add_feature_custom_themes).
- Multi-profile instances - run several Desktops side by side via
CLAUDE_PROFILE (fix_profile_*).
- Quick Entry - global hotkey popup, multi-monitor + Wayland-safe (
fix_quick_entry_*).
Features the app exposes that the official build already provides (we just preserve them through the repackage):
- Chat - main conversational UI.
- Claude Code - auto-detects system
claude CLI; Code tab + integrated terminal.
- Cowork - delegate a goal to a sandboxed Claude Code agent that reads/edits/creates files and returns a deliverable. Runs on the official native Cowork VM backend bundled in the
.deb (no separate daemon needed). Requires /dev/kvm.
- Browser Tools - Chrome automation via the Claude-in-Chrome extension/MCP.
- 3P / Enterprise gateway - configure external inference (Bedrock/Vertex/Azure/gateway); managed config from
/etc/claude-desktop/managed-settings.json; ion-dist 3P-config SPA.
- Imagine - in-Cowork image generation.
baseline/ tracks version-sensitive internals (re-validate each release): CLAUDE_FEATURE_FLAGS.md (flag catalog, GrowthBook IDs, 3-layer override), CLAUDE_BUILT_IN_MCP.md (internal MCP servers), ION.md (3P-config SPA stats/hashes), PLATFORM_GATE_BASELINE.md (every darwin/win32 gate classified PATCHED/NATIVE/STUB/PORTABLE).
claude-cowork-service - DEPRECATED
Historically this project shipped a sibling Go daemon (claude-cowork-service, binary cowork-svc-linux) that filled the role the macOS/Windows VM layer plays for Cowork: it reverse-engineered the length-prefixed-JSON-over-Unix-socket RPC protocol and ran the claude CLI either directly on the host (native mode) or in a QEMU/KVM guest. It is now deprecated/archived. The official Linux .deb bundles its own native Cowork VM backend, so the daemon is no longer needed or installed. Existing references in baseline/ and CHANGELOG.md are historical record.
USPs
Project vs the official build: brings Claude Desktop to the distros Anthropic does not package (Arch, Fedora/RHEL, Nix, AppImage); adds Computer Use (not in the official Linux beta), custom themes, multi-profile, and Quick Entry; open source.
How it fits
Anthropic official Claude Desktop Linux .deb (Electron 42.5.1 + native Cowork VM backend)
│ download → verify GPG+SHA256 → dpkg-deb -x → asar extract
▼
claude-desktop-bin (48 JS patches: Linux fixes + Computer Use + themes + profiles + Quick Entry)
│ asar pack → tarball
▼
AUR / our .deb / .rpm / .AppImage / Nix
