Linux Support

[LeonardoPiel]

Summary

Adds Linux AppImage build support and desktop launcher integration, making Open Cowork a fully usable desktop application on Linux.

Three changes:

1. Fix scripts/prepare-python.js — The prepare:python:all build step unconditionally installs pyobjc-framework-Quartz, a macOS-only package that has no Linux wheel. This broke npm run build on Linux. The fix filters out pyobjc packages when building for non-darwin platforms.

2. New scripts/install-linux-desktop.sh — Automates the XDG desktop entry setup: copies the AppImage to ~/.local/bin/, installs the icon, creates a .desktop file in ~/.local/share/applications/, and refreshes the desktop database. After running, the app appears in the Linux application launcher (Super key).

3. Update readme.md — Adds Linux to the platform badge and intro, documents the .AppImage download option in the installation table, adds a Linux Desktop Integration section with both the automated script and manual steps, and updates the FAQ to reflect Linux support.

Fixes electron-builder producing a valid Linux AppImage that was previously blocked during build.

Type of change

• Bug fix (fix)
• New feature (feat)
• Documentation (docs)

Checklist

• Code follows the project style (TypeScript strict, ESLint, Prettier)
• Commit messages follow Conventional Commits (feat:, fix:, etc.)
• Self-review completed — no debug logs, no commented-out code
• Tests added or updated for the changed behaviour (N/A — build script changes, no existing test suite for build scripts)
• npm run test passes locally (N/A — no runtime logic changed)
• npm run lint passes locally (prettier ran automatically via lint-staged on commit)
• UI changes tested on both macOS and Windows (Linux-specific change, tested on Ubuntu 7.0.11)
• New user-facing strings added to i18n files (N/A — CLI output only)

Testing

1. Built the AppImage on Linux with OPEN_COWORK_PYTHON_STANDALONE_URL_LINUX_X64 set to a python-build-standalone release URL → build completed successfully.
2. Ran scripts/install-linux-desktop.sh → AppImage copied, icon installed, .desktop file created, update-desktop-database executed without errors.
3. Launched ~/.local/bin/open-cowork → App started, detected running instance, exited cleanly.
4. Tested error path (nonexistent directory) → script exits 1 with clear error message.
5. Verified the macOS build path is unchanged — pyobjc still installed on darwin only.

Screenshots / recordings (if applicable)

N/A — no UI changes.

[github-actions]

Review mode: initial

Findings

• [Major] Manual desktop entry in readme uses literal $USER instead of expanded value (readme.md:130-139)

  • The heredoc uses single-quoted << 'EOF', so $USER is not expanded. The resulting .desktop file will contain /home/$USER/.local/bin/open-cowork literally, which will not work.
  • Suggested fix: Use double-quoted heredoc or expand the variable outside, e.g.:

    cat > ~/.local/share/applications/open-cowork.desktop << EOF
    [Desktop Entry]
    ...
    Exec=$HOME/.local/bin/open-cowork %U
    ...
    EOF

• [Major] AppImage glob pattern in install-linux-desktop.sh likely does not match standard electron-builder output (scripts/install-linux-desktop.sh:25)

  • The pattern Open Cowork-*-linux-*.AppImage expects "linux" in the filename, but electron-builder typically produces Open Cowork-<version>.AppImage (e.g., Open Cowork-3.3.1.AppImage). The script will fail to locate the AppImage in most cases.
  • Suggested fix: Change the pattern to Open Cowork-*.AppImage (more permissive) or use a more specific pattern based on actual build output.

• [Minor] Icon extraction fallback may fail to find the icon (scripts/install-linux-desktop.sh:78-83)

  • The fallback attempts to extract a specific icon name (open-cowork.png) from the AppImage, but the actual icon inside may have a different name or path. If extraction fails silently and the source resources/icon.png is missing, the desktop entry will have no icon.
  • Suggested fix: After extracting, use find to locate any .png file and copy it, or bundle the icon in the repo and ensure it is present before release.

• [Nit] Large package-lock.json changes with many peer: true flags added/removed (package-lock.json)

  • These changes appear to be generated by npm and may be unintentional. They introduce noise and could affect dependency resolution. Ensure they are necessary and consistent with the project's lockfile policy.

Summary
Review mode: initial

The PR introduces Linux AppImage support with helpful build fixes and a desktop integration script. The core logic in prepare-python.js is correct. However, two blocking issues in the user-facing documentation and installer script will prevent a smooth experience: the manual .desktop entry in readme.md has unexpanded $USER, and the AppImage file find pattern does not match the actual build output. These should be fixed before merging.

Testing
Not run (automation). No tests added for the new install script or the modified build script; consider adding smoke tests for prepare-python.js filter logic.

Open Cowork Bot