johnzfitch/claude-cowork-linux: a reverse-engineered port with a five-month stale AUR window

Four steps that amount to disabling a platform check

Cowork is a special Claude Desktop build that works inside a folder you point it at, reading, writing and organizing files there while it runs a plan. Upstream it is a macOS-only preview backed by a sandboxed Linux VM. This project removes the VM layer and runs on Linux x86_64 directly.

The mechanism is four steps. Stubbing replaces the macOS-only native modules `@ant/claude-swift` and `@ant/claude-native` with JavaScript, held in the stubs/ directory in this tree. Direct execution runs the Claude Code binary on the host, with the reasoning stated plainly in the docs: no VM is needed because you are already on Linux. Path translation converts VM paths to host paths so the app looks in the right place. And platform spoofing sends macOS headers so the server turns the feature on for a client that is not a Mac.

That last step is the honest headline. The feature is enabled by claiming to be a different operating system, which is why the status section leads with an unofficial research preview warning that the work is reverse-engineered and may break when Claude Desktop updates. The patching itself lives in enable-cowork.py and patch-index.sh, with index.js at the root and a Nix path in nix/.

The AUR recipe served a stale pkgrel for five months with no error

The Arch route carries the most interesting failure in the whole file, and the project documents it at length.

yay -S claude-cowork-linux

The AUR listing is pushed by a workflow that can fail, and when it does the package keeps serving an older recipe with nothing to say so. Between 2026-04-23 and the fix for issue 189, the publish workflow failed on a bad signing key for five months, so `yay -S` kept building `pkgrel` 10 while the repository moved on to 13.

What makes it worse is how it fails. The recipe's source line clones this repository at `master` with no tag pinned, so a stale build recipe drives current helper scripts. You get today's `enable-cowork.py` invoked the way a recipe from months ago invoked it, and on a split-entry Claude Desktop bundle that points the patcher at the index.js shim alone and produces:

ERROR: Platform-gate function not found in .../.vite/build/index.js

That message reads like a new bundle layout, and it is not one. The fix shipped is that enable-cowork.py now recognizes that shape and says so, but only once the stale recipe reaches the point of calling it. A sync check ships for exactly this purpose:

./check-aur-sync.sh

Root carries both PKGBUILD and .SRCINFO, so the recipe is readable in the tree, and the comparison is the recommended habit rather than trusting the published package.

Four install routes with four different behaviors

The recommended route is the repository installer, which prompts before downloading the Claude Desktop asar so you can confirm the version:

git clone https://github.com/johnzfitch/claude-cowork-linux.git
cd claude-cowork-linux
./install.sh          # prompts before downloading the Claude Desktop asar
claude-desktop

`--force` or `--yes` skips the prompt for scripted runs. The AUR route is the stale-recipe one above. The piped route exists but has a rule of its own:

bash <(curl -fsSL https://raw.githubusercontent.com/johnzfitch/claude-cowork-linux/master/install.sh)

Piped, non-interactive installs refuse to download without an explicit confirmation flag, so the working form appends `--force`. You can also point the installer at an archive you already have, either as an argument or through an environment variable:

./install.sh ~/Downloads/Claude-*.dmg
# or
CLAUDE_ARCHIVE=~/Downloads/Claude-1.6259.1.dmg ./install.sh

NixOS gets a fourth path because install.sh cannot run there. The package-manager branch uses imperative `nix-env -iA`, and the npm `electron` it would otherwise install is a prebuilt ELF that does not run on NixOS, so the flake builds against `electron_41` from nixpkgs instead, either run directly or added to a systemPackages list. All three non-AUR routes build from this repository, which is the point the sync-check section makes.

Most distros are Expected, and only two are Tested

The compatibility table is unusually honest about its own coverage. Arch Linux with Hyprland on Wayland is Tested and named the primary development environment. openSUSE is also Tested, with the note that it uses the `7zip` package rather than `p7zip` and `nodejs-default` for Node.js. Everything else is Expected rather than confirmed: Arch with KDE Plasma, where KDE Wallet is exposed over the SecretService D-Bus, Arch with GNOME, where global shortcuts need manual desktop configuration because GNOME lacks portal support, Ubuntu 22.04 and later where gnome-keyring provides SecretService, Fedora 39 and later which may need `p7zip-plugins` for DMG extraction, and Debian 12 or later with `p7zip-full` from apt. NixOS is the only Untested row, flagged for Electron plus bubblewrap sandboxing needing extra configuration.

Two environment checks exist for after the fact. `./install.sh --doctor`, or `claude-desktop --doctor`, validates the environment once installed.

The requirement list is correspondingly heavy for something that presents as a convenience: Node.js 18 or newer with npm, Electron, asar via `npm install -g @electron/asar`, p7zip for extracting the macOS DMG, bubblewrap for sandbox isolation, Python 3.11 or newer optionally for the patching step, a Claude Pro or higher subscription for Cowork access, and a SecretService provider if you want credentials anywhere but on disk. The reference machine is Arch on kernel 6.18.13.

Without a keyring the launcher falls back to plaintext on disk

The secret storage story has a documented insecure default. If `gnome-keyring` or another SecretService provider is not running, the launcher falls back to `--password-store=basic`, which the docs state plainly means credentials are stored on disk rather than in a keyring.

Nothing warns before this happens at runtime. You find out by checking which provider is active, which is what the doctor mode is for. The supported providers are named as gnome-keyring, KDE Wallet and KeePassXC.

The other documented caveat is a global hotkey. Wayland compositors that do not implement the `GlobalShortcuts` portal, GNOME being the named case, get no global hotkey support and the advice is to set a custom shortcut in your desktop settings instead. A third caveat is the session symlink: the `/sessions` root symlink needs `sudo` once during install, and on distros that restrict root symlinks differently you point it at the target yourself with `sudo ln -s "$HOME/.config/Claude/local-agent-mode-sessions/sessions" /sessions`. Each of these three is a place where the port quietly differs from the macOS original.

package.json sits two releases behind the newest tag

The tree ships its own version marker, and it is behind. package.json reads version 5.1.0, marked private with only two devDependencies, `@electron/asar` at ^3.2.0 and `devtron` at ^1.4.0, and no runtime dependencies at all. Nothing in that file describes a runnable application, which fits a project whose output is a patcher plus stubs installed onto someone else's binary.

The tagged releases run ahead of it. The newest is v5.2.0 from 2026-07-02, named Open Sesame, with v5.1.0 from 2026-06-05 and v5.0.0 from 2026-05-07 named "{ success: true } The Asar Believes It". Two of the three carry the asar bundling in their names, which matches the patching approach.

The last push landed on 2026-09-22, roughly two and a half months after the v5.2.0 tag, and the repository is not archived. That gap is not necessarily a problem in a repository that publishes through a separate AUR workflow, but it does mean the manifest version is the wrong number to quote when comparing against what an installer produced.

The test suite targets the seams, not Claude itself

The claim about tests is specific enough to check. There are 571 test cases across 36 test files, validating IPC, path translation, security and session persistence, plus four shell suites covering the patch passes, compat pins, launcher stub sync and install-script static analysis. All of it runs in CI on every push and pull request.

What that list makes clear is the boundary of what can be tested. Path translation, session persistence, the compat pins and the install script are all properties of this repository, so they are assertable. Whether the spoofed headers still satisfy the server after a Claude Desktop update is not, which is the same thing the reverse-engineering caveat says.

The tree supports that reading. validate.sh, test-local.sh, launch-devtools.sh, launch.sh and check-aur-sync.sh sit at the root, tests/ holds the suite, COMPAT.md holds the tested-versions matrix that the install prompt points you at, and config/ holds the packaging bits. There is also SECURITY.md and CONTRIBUTING.md, and docs/ for the longer material.

Editorial conclusion

Use the repository installer rather than the AUR package, and run check-aur-sync.sh before trusting either. This is a reverse-engineered port of a preview feature, so a Claude Desktop update can break it without warning, and the project says so. Verify your session symlink exists at /sessions, confirm a SecretService provider is running so credentials do not land in the basic password store, and check COMPAT.md for the tested version matrix before you point it at a folder you care about.

Frequently asked questions

Official sources

1. johnzfitch/claude-cowork-linux on GitHub
2. License: MIT
3. Project website
4. README
5. Releases