$ show ilysenko/codex-desktop-linux
This repository is a community distribution and feature-extension framework for OpenAI's ChatGPT desktop application on Linux. It does not contain the core ChatGPT application itself; instead, it verifies, repackages, and patches the official signed upstream .deb package to produce customized builds for multiple Linux package formats (deb, RPM, pacman, AppImage, Nix, Gentoo ebuild). The system adds over 40 optional Linux-specific featuresβsuch as system tray integration, global dictation, computer-use automation (window management, accessibility, screenshots), desktop recording/replay, text-to-speech, proxy authentication, and UI tweaksβeach gated behind a declarative feature manifest and applied via a sophisticated patch engine that modifies the Electron app bundle at build time. Architecturally, the project is a build/packaging/update framework. The core is a patch engine (scripts/patches/) that applies declarative descriptors to the upstream app.asar in phases (main-bundle, webview-asset, extracted-app). Features live under linux-features/ with standardized manifests (feature.json), patch scripts (patch.js), stage hooks, and tests. Performance-critical subsystems are implemented in Rust: a computer-use backend (window management, input simulation, accessibility tree), a record-replay backend (desktop session capture, timeline events, skill drafting), a text-to-speech MCP server, a global dictation helper, and a self-updating package manager daemon. The launcher (start.sh.template) orchestrates environment setup, feature hooks, and CLI dispatch. Key entry points include the installer (install.sh), the feature picker GUI (scripts/feature-picker.py), the patch runner (scripts/patches/runner.js), and the updater daemon (updater/src/main.rs). Data flows are primarily build-time: the upstream .deb is downloaded, verified via GPG/SHA256, extracted, patched, and repackaged. At runtime, features like computer-use and record-replay communicate with native Rust backends over MCP/JSON-RPC. The updater daemon runs as a systemd user service, polling signed APT metadata and performing transactional rebuilds with rollback support. External dependencies include the upstream OpenAI .deb package (the sole ground-truth source), Node.js for patching, Rust for native components, and various Linux system tools (systemd, D-Bus, GNOME Shell, X11/Wayland utilities, ydotool, wmctrl, xdotool, secret-tool). The build system uses Make, Docker for CI, and supports multiple package managers. The project is heavily dependent on the upstream bundle's minified JavaScript structure, which it manages through contract-based patching with drift detection.
The LLM identified 5 files worth highlighting for reuse:
Core patch descriptor system that standardizes how all feature patches are defined. Each patch exports a descriptors array with id, phase (main-bundle, webview-asset, extracted-app), order, ciPolicy (required-upstream, optional, opt-in), assetMatch for targeting specific bundle files, and an apply function. The framework supports contract validation (expected source patterns must match before applying), idempotent application (checks for existing markers), and drift detection (warns on pattern mismatch). This pattern is reusable for any project that needs to apply version-sensitive modifications to third-party bundles with safety guarantees.
Provides atomic, crash-safe file and directory operations for the record-replay subsystem. Implements write_private_file (temp+rename with fsync), append_private_line, create_private_dir_all, and lock_directory with stale-PID recovery. All operations enforce strict permissions (0o600/0o700) and reject symlink components to prevent TOCTOU attacks. The directory locking mechanism uses a PID file with boot-ID verification to detect and clean up stale locks. This module is self-contained and could be extracted as a reusable Rust crate for any application requiring secure local storage.
Defines the abstract windowing backend interface (Backend trait) and a registry that probes available backends in priority order. Each backend (GNOME Shell, KWin, Hyprland, i3, Niri, COSMIC, X11) implements list_windows, focus_window, and screenshot methods. The registry uses a static list of backend constructors, tries each with a probe() call, and returns the first successful one. This pattern cleanly separates window manager specifics from the computer-use logic and is reusable for any multi-environment automation tool that needs to support multiple desktop environments.
Implements a robust screenshot capture function with a fallback chain: GNOME Shell D-Bus β custom GNOME extension β XDG portal β X11 (via xdotool/xprop) β gnome-screenshot. Each backend is tried in order, with an environment variable (CODEX_COMPUTER_USE_SCREENSHOT_BACKEND) to force a specific backend. The function handles multi-monitor setups, scaled displays, and Wayland vs X11 detection. This pattern of trying multiple platform-specific backends with graceful degradation is reusable for any Linux application that needs reliable screenshot capture across diverse desktop configurations.
Implements a durable persisted state machine for the update manager daemon. Uses atomic file writes with JSON serialization, schema versioning (4 versions with migration), and crash-durable transaction journaling. The state tracks current version, pending update, rollback availability, and operation progress. File locking via advisory locks prevents concurrent access. The state machine supports manual recovery for interrupted operations (e.g., half-applied updates). This module is self-contained and could be reused as a generic Rust state persistence library for any daemon that requires crash-safe state management.