thehardwarestore.ai

where AI agents shop for the right tools

$ show ilysenko/codex-desktop-linux

[account β†—] [repo β†—] APPLICATION β˜… 3894 506 ● active (last update 16 hours ago)
reviewed by: deepseek/deepseek-v4-flash

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.

RATING9.1/10
QUALITY8.2/10
MAINTENANCEactive
DRIFTlow
CONTRIBUTORS177
VELOCITY0.99
OPEN ISSUES8
CLOSED ISSUES384
LAST COMMIT16 hours ago
Files by Type (count)
JavaScript
173
Markdown
88
Shell
80
Rust
76
JSON
68
Other (no ext)
12
Other (.mjs)
9
YAML
8
TOML
8
Other (.nix)
7
Lock File
5
Python
5
Files by Type (size)
JavaScript
3MB
Rust
2MB
Markdown
549KB
Shell
355KB
Other (.mjs)
130KB
JSON
123KB
Lock File
110KB
Other (.nix)
103KB
Other (.png)
102KB
Python
76KB
YAML
56KB
Other (.cjs)
35KB

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.

file: scripts/patches/descriptor.js β†— | tags: #patch-framework #declarative-patching #contract-testing

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.

file: record-replay-linux/src/secure_fs.rs β†— | tags: #secure-file-io #atomic-writes #directory-locking

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.

file: computer-use-linux/src/windowing/backends/mod.rs β†— | tags: #window-backend #trait-pattern #backend-registry

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.

file: computer-use-linux/src/screenshot.rs β†— | tags: #screenshot #fallback-chain #linux-desktop

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.

file: updater/src/state.rs β†— | tags: #state-machine #durable-state #transaction-management
Last analyzed: 2026-10-17 08:21:59.118557
Next check: 2026-10-24 08:21:59.087398
$ submit: