https://github.com/johnzfitch/claude-cowork-linux
Run Claude Desktop’s Cowork mode natively on Linux — no macOS or VM required
https://github.com/johnzfitch/claude-cowork-linux
anthropic arch-linux asar aur claude claude-ai claude-api claude-code claude-desktop cowork desktop-app electron linux local-agent-mode native-module-stub nodejs wayland x11
Last synced: 3 days ago
JSON representation
Run Claude Desktop’s Cowork mode natively on Linux — no macOS or VM required
- Host: GitHub
- URL: https://github.com/johnzfitch/claude-cowork-linux
- Owner: johnzfitch
- License: mit
- Created: 2026-01-14T13:08:48.000Z (3 months ago)
- Default Branch: master
- Last Pushed: 2026-03-16T07:04:18.000Z (20 days ago)
- Last Synced: 2026-03-16T08:46:05.373Z (20 days ago)
- Topics: anthropic, arch-linux, asar, aur, claude, claude-ai, claude-api, claude-code, claude-desktop, cowork, desktop-app, electron, linux, local-agent-mode, native-module-stub, nodejs, wayland, x11
- Language: JavaScript
- Homepage: https://github.com/johnzfitch/claude-cowork-linux/releases
- Size: 844 KB
- Stars: 79
- Watchers: 1
- Forks: 17
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# Claude Cowork on Linux
### No macOS, no VM required.
**[Quick Start](#-quick-start)** · **[How It Works](#-how-it-works)** · **[Manual Setup](#-manual-setup)** · **[Troubleshooting](#-troubleshooting)**
---
##  Overview
Claude Cowork is a special Claude Desktop build that works inside a folder you point it at—it reads, writes, and organizes files there while it runs a plan. Cowork is currently a **macOS-only preview** backed by a sandboxed Linux VM; this repo reverse-engineers and stubs the macOS-native pieces so Cowork can run directly on Linux (x86_64)—no VM and no macOS required. The stub translates VM paths to host paths so Cowork points at the right files on Linux.
**How it works:**
| Step | Description |
|:-----|:------------|
|  **Stubbing** | Replace macOS-only native modules (`@ant/claude-swift`, `@ant/claude-native`) with JavaScript |
|  **Direct Execution** | Run the Claude Code binary directly (no VM needed—we're already on Linux!) |
|  **Path Translation** | Convert VM paths to host paths transparently |
|  **Platform Spoofing** | Send macOS headers so the server enables the feature |
---
##  Status
- **Unofficial research preview**: This is reverse-engineered and may break when Claude Desktop updates.
- **Linux support**: Currently targets **Linux x86_64**. Wayland: auto-detected via `$WAYLAND_DISPLAY` / `$XDG_SESSION_TYPE` (Ozone backend).
- **Access**: Requires a Claude account. The installer auto-downloads the Claude Desktop DMG; no macOS machine needed.
- **Tests**: 215+ test cases across 18 test files validating IPC, path translation, security, and session persistence.
---
##  Compatibility
| Distro | Desktop | Status | Notes |
|:-------|:--------|:-------|:------|
| **Arch Linux** | Hyprland (Wayland) | Tested | Primary dev environment |
| **Arch Linux** | KDE Plasma (Wayland) | Expected | KDE Wallet exposed via SecretService D-Bus |
| **Arch Linux** | GNOME (Wayland) | Expected | Global shortcuts require manual DE config (GNOME lacks portal support) |
| **Ubuntu 22.04+** | GNOME / X11 | Expected | gnome-keyring provides SecretService |
| **Fedora 39+** | GNOME / KDE | Expected | May need `p7zip-plugins` for DMG extraction |
| **Debian 12+** | Any | Expected | `p7zip-full` in apt |
| **NixOS** | Any | Untested | Electron + bwrap sandboxing may need extra config |
| **openSUSE** | Any | Tested | Uses `7zip` package (not `p7zip`); `nodejs-default` for Node.js |
**Known caveats:**
- Wayland compositors that don't implement the `GlobalShortcuts` portal (GNOME) won't have global hotkey support -- set a custom shortcut in your DE settings instead.
- If `gnome-keyring` or another SecretService provider isn't running, the launcher falls back to `--password-store=basic` (credentials stored on disk, not in a keyring).
- The `/sessions` root symlink requires `sudo` once during install. If your distro restricts root symlinks differently, point it manually: `sudo ln -s "$HOME/.config/Claude/local-agent-mode-sessions/sessions" /sessions`.
Run `./install.sh --doctor` (or `claude-desktop --doctor`) after install to validate your environment.
---
##  Requirements
- **Linux x86_64** (tested on Arch Linux, kernel 6.18.13)
- **Node.js 18+** / npm
- **Electron** (system package or npm global)
- **asar** (`npm install -g @electron/asar`)
- **p7zip** (to extract the macOS DMG; openSUSE uses `7zip` instead)
- **bubblewrap** (sandbox isolation)
- **Python 3.11+** (optional, for `enable-cowork.py` patching — the installer uses Node.js to download DMGs)
- **Claude Pro** (or higher) subscription for Cowork access
- **Secret service provider** (optional) -- gnome-keyring, KDE Wallet, or KeePassXC for secure credential storage. Without one, the launcher falls back to `--password-store=basic`.
---
##  Quick Start
### Method 1: install.sh (recommended)
```bash
git clone https://github.com/johnzfitch/claude-cowork-linux.git
cd claude-cowork-linux
./install.sh # auto-downloads the latest DMG via Node.js
claude-desktop
```
### Method 2: AUR (Arch Linux)
```bash
yay -S claude-cowork-linux # auto-downloads the latest DMG
```
### Method 3: curl pipe
```bash
bash <(curl -fsSL https://raw.githubusercontent.com/johnzfitch/claude-cowork-linux/master/install.sh)
```
The installer automatically downloads the latest Claude Desktop DMG using Node.js (`scripts/fetch-dmg.js`). You can also provide a DMG manually:
```bash
./install.sh ~/Downloads/Claude-*.dmg
# or
CLAUDE_DMG=~/Downloads/Claude-1.1.4010.dmg ./install.sh
```
> [!IMPORTANT]
> This repo does not include Anthropic's proprietary code. The installer downloads it directly from Anthropic's CDN.
---
##  Architecture
```
┌─────────────────────────────────────────────────────────────────┐
│ Claude Desktop (Electron) │
├─────────────────────────────────────────────────────────────────┤
│ @ant/claude-swift (STUBBED) │
│ ├── vm.setEventCallbacks() → Register process event handlers │
│ ├── vm.startVM() → No-op (we're already on Linux) │
│ ├── vm.spawn() → Delegates to session orchestrator │
│ ├── vm.kill() → Kills spawned processes │
│ └── vm.writeStdin() → Writes to process stdin │
├─────────────────────────────────────────────────────────────────┤
│ @ant/claude-native (STUBBED) │
│ ├── AuthRequest → Opens system browser (xdg-open) │
│ └── Platform helpers → Minimal compatibility shims │
├─────────────────────────────────────────────────────────────────┤
│ stubs/cowork/ — Orchestration Layer (15 modules) │
│ ├── session_orchestrator.js → Coordinates spawn lifecycle │
│ ├── asar_adapter.js → Asar IPC API compatibility │
│ ├── process_manager.js → Process lifecycle & I/O │
│ ├── resume_coordinator.js → Session resume logic │
│ ├── sessions_api.js → Session CRUD operations │
│ ├── session_store.js → In-memory session state │
│ ├── transcript_store.js → Transcript persistence │
│ ├── file_registry.js → Working directory tracking │
│ ├── file_watch_manager.js → File change detection │
│ ├── stream_protocol.js → JSON-RPC stream parsing │
│ ├── credential_classifier.js → Token leak prevention │
│ ├── eipc_channel.js → EIPC message protocol │
│ ├── ipc_tap.js → IPC channel discovery │
│ ├── dirs.js → XDG directory resolution │
│ └── file_identity.js → Path normalization │
├─────────────────────────────────────────────────────────────────┤
│ Claude Code Binary │
│ └── Resolved from ~/.local/bin, mise/asdf shims, PATH, etc. │
│ (launch.sh replaces macOS Mach-O binary with Linux symlink)│
└─────────────────────────────────────────────────────────────────┘
```
### Path Translation
The stub translates VM paths to host paths:
| VM Path | Host Path |
|:--------|:----------|
| `/usr/local/bin/claude` or `claude` | Resolved via `~/.local/bin/claude`, `~/.config/Claude/claude-code-vm/{version}/claude`, or PATH |
| `/sessions/...` | `~/.config/Claude/local-agent-mode-sessions/sessions/...` |
### Mount Symlinks
When you select a folder in Cowork, the stub creates symlinks to make it accessible at the expected VM path:
```
~/.config/Claude/local-agent-mode-sessions/sessions//mnt/
├── → /home/user/path/to/selected/folder (symlink)
├── .claude → ~/.config/Claude/local-agent-mode-sessions/.../session/.claude (symlink)
├── .skills → ~/.config/Claude/local-agent-mode-sessions/skills-plugin/... (symlink)
└── uploads/ (directory for file uploads)
```
The `additionalMounts` parameter from Claude Desktop provides the mapping between mount names and host paths.
> [!NOTE]
> The Claude Code binary expects `/sessions` to exist. `install.sh` creates `/sessions` as a symlink into `~/.config/Claude/local-agent-mode-sessions/sessions` (requires `sudo` once) so you don't need a world-writable root directory.
---
##  How It Works
1. Platform Spoofing
The app sends these headers to Anthropic's servers:
```javascript
'Anthropic-Client-OS-Platform': 'darwin'
'Anthropic-Client-OS-Version': '14.0'
```
This makes the server think we're on macOS 14 (Sonoma), enabling Cowork features.
2. Platform Gate Bypass
The platform-gate function (minified name changes per build — `xPt()` in v1.1.3963, `wj()` in older builds) checks if Cowork is supported. `enable-cowork.py` finds it automatically and replaces it to unconditionally return `{status: "supported"}`.
3. Swift Addon Stub
The original `@ant/claude-swift` uses Apple's Virtualization Framework. Our stub:
- Implements the same API surface
- Delegates spawn logic to `session_orchestrator.js` for proper lifecycle management
- Line-buffers JSON output for proper stream parsing
- Translates VM paths to host paths
Key insight: The app calls `Si()` which returns `module.default.vm`, so methods must be on the `vm` object.
4. Native Utilities Stub
The app also expects `@ant/claude-native` (a macOS-specific native module). Our stub provides minimal compatibility so the app can start on Linux. For example, OAuth flows fall back to opening the system browser via `xdg-open`.
5. Session Orchestration Layer
The `stubs/cowork/` orchestration layer provides 15 modules that handle session lifecycle, IPC communication, transcript persistence, and security:
- **session_orchestrator.js** coordinates all spawn operations, mount symlinks, and process cleanup
- **credential_classifier.js** prevents auth token leakage to spawned processes
- **ipc_tap.js** discovers EIPC channels at runtime by tapping `ipcMain._invokeHandlers.set()`
- **transcript_store.js** persists conversation history to `~/.config/Claude/local-agent-mode-sessions/`
- **file_watch_manager.js** detects file changes in the working directory
All modules follow XDG Base Directory conventions and are tested with 215+ test cases.
6. Direct Execution
On macOS, Cowork runs a Linux VM. On Linux, we skip the VM entirely and run the Claude Code binary directly on the host. This is actually simpler and faster!
The stub resolves the binary in priority order:
```
$CLAUDE_CODE_PATH (explicit override)
~/.config/Claude/claude-code-vm/{version}/claude (downloaded by Desktop)
~/.local/bin/claude (npm/bun global)
~/.npm-global/bin/claude
/usr/local/bin/claude
/usr/bin/claude
/home/linuxbrew/.linuxbrew/bin/claude (Linuxbrew system)
~/.linuxbrew/bin/claude (Linuxbrew user)
~/.local/share/mise/shims/claude (mise version manager)
~/.asdf/shims/claude (asdf version manager)
```
**Code tab binary fixup**: `launch.sh` automatically detects if the Claude Code binary in the asar is a macOS Mach-O binary and replaces it with a symlink to the host Linux binary. This enables the Code tab to work seamlessly.
---
##  Project Structure
```
claude-cowork-linux/
├── stubs/
│ ├── @ant/claude-swift/js/index.js # Primary stub: vm.spawn() → delegates to orchestrator
│ ├── @ant/claude-native/index.js # Auth (xdg-open), keyboard constants, platform helpers
│ ├── cowork/ # Orchestration layer (15 modules)
│ │ ├── session_orchestrator.js # Spawn lifecycle coordinator
│ │ ├── asar_adapter.js # Asar IPC API compatibility
│ │ ├── process_manager.js # Process lifecycle & I/O
│ │ ├── resume_coordinator.js # Session resume logic
│ │ ├── sessions_api.js # Session CRUD operations
│ │ ├── session_store.js # In-memory session state
│ │ ├── transcript_store.js # Transcript persistence
│ │ ├── file_registry.js # Working directory tracking
│ │ ├── file_watch_manager.js # File change detection
│ │ ├── stream_protocol.js # JSON-RPC stream parsing
│ │ ├── credential_classifier.js # Token leak prevention
│ │ ├── eipc_channel.js # EIPC message protocol
│ │ ├── ipc_tap.js # IPC channel discovery
│ │ ├── dirs.js # XDG directory resolution
│ │ └── file_identity.js # Path normalization
│ └── frame-fix/
│ ├── frame-fix-wrapper.js # Early bootstrap: TMPDIR fix, platform spoofing, graceful shutdown
│ └── frame-fix-entry.js # Entry point: loads frame-fix-wrapper then main index.js
├── tests/
│ ├── node/current-path/ # 18 test files, 215+ node:test cases
│ │ ├── asar_adapter.test.cjs
│ │ ├── credential_classifier.test.cjs
│ │ ├── dirs.test.cjs
│ │ ├── eipc_channel.test.cjs
│ │ ├── file_identity.test.cjs
│ │ ├── file_registry.test.cjs
│ │ ├── file_watch_manager.test.cjs
│ │ ├── ipc_tap.test.cjs
│ │ ├── process_manager.test.cjs
│ │ ├── resume_coordinator.test.cjs
│ │ ├── session_orchestrator.test.cjs
│ │ ├── session_store.test.cjs
│ │ ├── sessions_api.test.cjs
│ │ ├── stream_protocol.test.cjs
│ │ ├── transcript_store.test.cjs
│ │ └── ... (integration tests)
│ ├── test-install-paths.sh # 8-stage install validation (static analysis → Docker)
│ └── Dockerfile.test # Arch Linux container for full install testing
├── scripts/
│ ├── fetch-dmg.js # Auto-download Claude DMG via Node.js fetch
│ └── enable-cowork.py # Patches platform gate to return {status:"supported"}
├── docs/
│ ├── FAQ.md # Detailed troubleshooting guide
│ ├── extensions.md # MCP and Chrome Extension integration overview
│ ├── known-issues.md # Safe Storage encryption, keyring setup
│ └── safestorage-tokens.md # How to persist tokens across restarts
├── config/
│ └── hyprland/claude.conf # Optional: Hyprland window rules
├── .github/assets/ # README icons and hero image
├── install.sh # Installer + --doctor preflight diagnostics
├── launch.sh # Launcher: syncs stubs, repacks asar, runs electron
├── launch-devtools.sh # Launcher with --inspect (Node.js DevTools)
├── validate.sh # Env var checks, stub URL validation, log scanning
├── PKGBUILD # Arch Linux AUR package definition
├── docs/releases/ # Per-version release notes
├── docs/OAUTH-COMPLIANCE.md # OAuth token handling audit
├── CLAUDE.md # Project guide and critical paths
├── README.md # This file
└── LICENSE
```
After running `install.sh`, the `linux-app-extracted/` directory will contain the extracted Claude Desktop.
---
##  Manual Setup
If the automated installer doesn't work, follow these steps:
1. Extract Claude Desktop from DMG
The installer handles `app.asar` extraction automatically. For manual extraction or older unpacked versions:
```bash
# Extract DMG with 7z
7z x Claude-*.dmg -o/tmp/claude-extract
# Create app directory
mkdir -p linux-app-extracted
# For newer versions (app.asar):
if [ -f "/tmp/claude-extract/Claude/Claude.app/Contents/Resources/app.asar" ]; then
npx --yes asar extract "/tmp/claude-extract/Claude/Claude.app/Contents/Resources/app.asar" linux-app-extracted
# Copy unpacked files if they exist
[ -d "/tmp/claude-extract/Claude/Claude.app/Contents/Resources/app.asar.unpacked" ] && \
cp -r "/tmp/claude-extract/Claude/Claude.app/Contents/Resources/app.asar.unpacked/"* linux-app-extracted/
# For older versions (unpacked app/):
elif [ -d "/tmp/claude-extract/Claude/Claude.app/Contents/Resources/app" ]; then
cp -r "/tmp/claude-extract/Claude/Claude.app/Contents/Resources/app/"* linux-app-extracted/
fi
# Cleanup
rm -rf /tmp/claude-extract
```
2. Install Stub Modules
```bash
# Copy our stubs over the original modules
cp -r stubs/@ant/* linux-app-extracted/node_modules/@ant/
cp -r stubs/cowork linux-app-extracted/node_modules/
```
3. Patch index.js
Run the cowork patch (auto-detects the minified function name):
```bash
python3 scripts/enable-cowork.py linux-app-extracted/.vite/build/index.js
```
4. Create Required Directories
```bash
# Create user session directory
mkdir -p "$HOME/.config/Claude/local-agent-mode-sessions/sessions"
chmod 700 "$HOME/.config/Claude/local-agent-mode-sessions/sessions"
# Create symlink (requires sudo once)
sudo ln -s "$HOME/.config/Claude/local-agent-mode-sessions/sessions" /sessions
```
5. Install Electron and asar
```bash
# System package (preferred)
# Arch: pacman -S electron
# Ubuntu/Debian: apt install electron
# Or via npm:
npm install -g electron @electron/asar
```
---
##  Troubleshooting
For detailed troubleshooting guides, see **[docs/FAQ.md](docs/FAQ.md)**.
Verify patches were applied
Check that the Cowork patch is present in `linux-app-extracted/.vite/build/index.js`:
```bash
grep -q 'cowork-patched' linux-app-extracted/.vite/build/index.js && echo "✓ Cowork patch applied" || echo "✗ Patch missing - run ./install.sh"
```
The patch replaces the platform-gate function to return `{status:"supported"}` unconditionally, enabling Cowork on Linux. The `/*cowork-patched*/` marker indicates successful patching.
EACCES: permission denied, mkdir '/sessions'
Create a symlink to user space instead of a world-writable directory:
```bash
mkdir -p "$HOME/.config/Claude/local-agent-mode-sessions/sessions"
sudo ln -s "$HOME/.config/Claude/local-agent-mode-sessions/sessions" /sessions
```
Unexpected non-whitespace character after JSON
JSON parsing issue. The stub uses line buffering to send complete JSON objects. If this persists, check the trace log:
```bash
cat ~/.local/state/claude-cowork/logs/claude-swift-trace.log
```
Failed to start Claude's workspace
Run `claude-desktop --doctor` first to check your environment. Then verify:
1. The swift stub is properly loaded (check for `[claude-swift-stub] LOADING MODULE` in logs)
2. The Claude binary exists at one of the resolved paths (`~/.local/bin/claude`, `~/.config/Claude/claude-code-vm/{version}/claude`, etc.)
3. You have a valid Claude account
Process exits immediately (code=1)
Check stderr in the trace log for the actual error:
```bash
tail -50 ~/.local/state/claude-cowork/logs/claude-swift-trace.log
```
Common issues:
- Missing `/sessions` symlink
- Binary not found
- Permission issues
t.setEventCallbacks is not a function
This means the stub isn't exporting methods correctly. The app expects:
- `module.default.vm.setEventCallbacks()` — NOT on the class directly
Ensure the stub has methods on the `this.vm` object, not just the class.
App won't relaunch / appears to do nothing
A previous instance may not have shut down cleanly, leaving a stale lock file. Clear it and relaunch:
```bash
rm -f ~/.config/Claude/SingletonLock ~/.config/Claude/SingletonSocket ~/.config/Claude/SingletonCookie
claude-desktop
```
Global shortcuts don't work on Wayland (GNOME)
The app enables `GlobalShortcutsPortal` for Wayland global shortcut support via `xdg-desktop-portal`. This works on **KDE Plasma** and **Hyprland** but **not on GNOME** — `xdg-desktop-portal-gnome` has not implemented the GlobalShortcuts portal yet.
**Workaround for GNOME Wayland users:** Set a custom shortcut in GNOME Settings > Keyboard > Custom Shortcuts to launch `claude-desktop`.
---
##  Development
```bash
./launch.sh # repacks asar automatically if stubs changed
./launch-devtools.sh # with Node.js inspector
./validate.sh # env var checks, stub URL validation, log errors
./install.sh --doctor # preflight: binaries, node, CLI, /sessions, secret service, patches
# Run tests
node --test tests/node/current-path/*.test.cjs
```
### Debug Logging
```bash
# Include Claude Code stdout/stderr in the trace log (redacted, but still treat logs as sensitive)
export CLAUDE_COWORK_TRACE_IO=1
# Enable debug mode
export CLAUDE_COWORK_DEBUG=1
# Enable Electron logging
export ELECTRON_ENABLE_LOGGING=1
# Clear old logs
rm -f ~/.local/state/claude-cowork/logs/claude-swift-trace.log
# Run with output capture
./launch.sh 2>&1 | tee /tmp/claude-full.log
# In another terminal, watch the trace
tail -f ~/.local/state/claude-cowork/logs/claude-swift-trace.log
```
### Trace Log Format
The stub writes to `~/.local/state/claude-cowork/logs/claude-swift-trace.log`:
```
[timestamp] === MODULE LOADING ===
[timestamp] vm.setEventCallbacks() CALLED
[timestamp] vm.startVM() bundlePath=... memoryGB=4
[timestamp] vm.spawn() id=... cmd=... args=[...]
[timestamp] Translated command: /usr/local/bin/claude -> ~/.config/Claude/...
[timestamp] stdout line: {"type":"stream_event",...}
[timestamp] Process ... exited: code=0
```
---
##  Security
This project includes security hardening:
- **Command allowlist** - Only vetted binary paths are accepted by `vm.spawn()`; unknown commands are rejected
- **Command injection prevention** - Uses `execFile()` instead of `exec()`
- **Path traversal protection** - Validates session paths with `isPathSafe()`
- **Environment filtering** - Allowlist of safe environment variables
- **Secure permissions** - Session directory uses 700, not 777
- **Symlink for /sessions** - No world-writable directories
- **URL origin validation** - `Auth_$_doAuthInBrowser` and `AuthRequest.start()` enforce Anthropic-only domains
- **OAuth compliance** - `BLOCKED_ENV_KEY_PATTERN` + `CREDENTIAL_EXEMPT_KEYS` prevent token leakage to subprocesses
- **Credential classification** - `credential_classifier.js` enforces strict token leak prevention with allowlist-based exemptions
- **CRLF guards** - Stream parsers reject CRLF injection attempts in JSON-RPC messages
- **FD bounds checking** - File descriptor limits enforced on spawned processes to prevent resource exhaustion
---
## Legal Notice
> [!CAUTION]
> This project is for **educational and research purposes**. Claude Desktop is proprietary software owned by Anthropic PBC. Use of Cowork requires a valid Claude account.
>
> This repository contains only stub implementations and patches—**not** the Claude Desktop application itself. You must obtain Claude Desktop directly from Anthropic.
>
> This project is **not affiliated with, endorsed by, or sponsored by** Anthropic. "Claude" is a trademark of Anthropic PBC.
---
## Credits
Reverse engineered and implemented by examining the Claude Desktop Electron app structure, binary analysis with pyghidra-lite, and iterative debugging.
**Contributors:**
- [@Boermt-die-Buse](https://github.com/Boermt-die-Buse) -- Linux UI fixes: native window frames, titlebar patch, icon extraction
- [@JaPossert](https://github.com/JaPossert) -- Resources copy fix, Wayland global shortcuts report
- [@alpham8](https://github.com/alpham8) -- openSUSE compatibility fixes, binary resolution paths, Swift stub method stubs
- [@matiasandina](https://github.com/matiasandina) -- icon fix and terminal detach proposals (issue #37)
---
**MIT License** · See [LICENSE](LICENSE) for details