English | 简体中文
CodexPlusPlus-on-Linux is a source-level Linux adaptation project for BigPizzaV3/CodexPlusPlus.
It records and reapplies the patches needed to make Codex++ work with the unofficial Linux Codex Desktop build produced by ilysenko/codex-desktop-linux.
Project version: 1.2.41, synchronized with upstream Codex++ v1.2.41.
This repository is maintained as a fork/adaptation of:
-
Codex++ upstream: https://github.com/BigPizzaV3/CodexPlusPlus
-
Linux Codex Desktop packaging reference: https://github.com/ilysenko/codex-desktop-linux
License: GPL-3.0-or-later. See LICENSE.
-
An Antora documentation component under
docs/. -
A structured snippet manifest in
docs/modules/ROOT/pages/snippets.adoc. -
The official maintenance workflow in
docs/modules/ROOT/pages/maintenance-workflow.adoc. -
A historical/experimental recurring adaptation workflow in
docs/modules/ROOT/pages/adapter-workflow.adoc. -
Patch attachments in
docs/modules/ROOT/attachments/patches/. -
A bilingual PowerShell installer and manager script:
scripts/developer/Installer-and-Manager.ps1. -
Upstream source snapshots under
CodexPlusPlus/srcandcodex-desktop-linux/srcfor research and reproducible comparison; nested.gitmetadata and local build caches are intentionally not tracked.
The manager script can install, update, uninstall, and reapply the Linux adaptation from an original Codex++ source package.
By default the script accepts either a repository-style layout:
$HOME/opt/codex-desktop-linux/codex-app/start.sh
$HOME/opt/codex-desktop-linux/codex-app/versionor a direct app-root layout, which is the layout used by this project’s validation workflow:
$HOME/opt/CodexDesktop/start.sh
$HOME/opt/CodexDesktop/versionThe default Codex++ adapter install path is .codex-plusplus under the detected Codex app directory.
For example:
$HOME/opt/codex-desktop-linux/codex-app/.codex-plusplus
$HOME/opt/CodexDesktop/.codex-plusplusFollow the README.md of https://github.com/ilysenko/codex-desktop-linux before installing this adapter.
The commands below are a practical example; review the upstream README for current platform-specific requirements.
$adapterRoot = "$HOME/opt/CodexPlusPlus-on-Linux"
$codexDesktopInstallPath = "$HOME/opt/CodexDesktop"
Set-Location $adapterRoot
pwsh ./scripts/developer/Build-CodexDesktopLinux.ps1 `
-Action build-install `
-SourceRoot "$adapterRoot/codex-desktop-linux/src" `
-InstallPath $codexDesktopInstallPath
New-Item -ItemType Directory -Force -Path "$HOME/.local/bin", "$HOME/.local/share/icons", "$HOME/.local/share/applications"
New-Item -ItemType SymbolicLink -Force `
-Path "$HOME/.local/bin/codex-desktop-linux" `
-Target (Join-Path $codexDesktopInstallPath 'start.sh' -Resolve)
New-Item -ItemType SymbolicLink -Force `
-Path "$HOME/.local/share/icons/codex-desktop.png" `
-Target (Join-Path $codexDesktopInstallPath '.codex-linux' 'codex-desktop.png' -Resolve)
$desktopFilePath = "$HOME/.local/share/applications/codex-desktop-linux.desktop"
Copy-Item -Path "contrib/user-local-install/files/.local/share/applications/codex-desktop.desktop" -Destination $desktopFilePath -Force
(Get-Content $desktopFilePath) -creplace '^Exec=.*', 'Exec=codex-desktop-linux' | Set-Content $desktopFilePathThe build script discovers every documented top-level feature in the pinned
codex-desktop-linux source except example-feature and local. It writes the
git-ignored linux-features/features.json, exports both
CODEX_LINUX_FEATURES and CODEX_LINUX_FEATURES_CONFIG, and rejects the build
unless both build-info files record the exact discovered set. The v1.2.41
baseline currently discovers 29 Linux features; Enabled features: None is a
hard build failure.
The ydotool installation command itself is distribution-specific; follow docs/linux-computer-use.md in ilysenko/codex-desktop-linux for the current package name and service setup.
To update the Linux Codex Desktop build, replace the Codex.dmg used by ilysenko/codex-desktop-linux, then rerun the same PowerShell build procedure.
Run the manager script with PowerShell:
pwsh ./scripts/developer/Installer-and-Manager.ps1 -Action install -CodexDesktopRootPath "$HOME/opt/CodexDesktop"The script defaults are intentionally conservative:
-
Codex Desktop root:
$HOME/opt/codex-desktop-linux -
Codex++ source: fetch
https://github.com/BigPizzaV3/CodexPlusPlus -
Codex++ install path:
.codex-plusplusunder the detected Codex app directory -
Regression test snippets: enabled
-
Update check prompt: disabled by default
When desktop entries are enabled, the script creates the upstream-style user entries
$HOME/.local/share/applications/codex-plus-plus.desktop and
$HOME/.local/share/applications/codex-plus-plus-manager.desktop.
They are named Codex` and `Codex Manager, reuse the Linux Codex Desktop icon when available, and replace older adapter-branded *-linux.desktop entries.
Install and update also remove the historical iconless
codex-desktop-linux.desktop template only when its original name, command,
and unexpanded @HOME@ TryExec marker all match. A custom entry that merely
uses the same filename is preserved.
The script has a configuration block at the top.
It supports shell-style path values such as $HOME/opt/CodexDesktop, ${HOME}/opt/CodexDesktop, $env:HOME/opt/CodexDesktop, and ~/opt/CodexDesktop.
pwsh ./scripts/developer/Installer-and-Manager.ps1 -Action update -CodexDesktopRootPath "$HOME/opt/CodexDesktop"The update action fetches or copies a fresh upstream source, reapplies enabled snippets, rebuilds, and replaces the installed adapter binaries.
pwsh ./scripts/developer/Installer-and-Manager.ps1 -Action uninstall -CodexDesktopRootPath "$HOME/opt/CodexDesktop"By default user scripts are preserved.
Change $PreserveUserScriptsOnUninstall in the script configuration block if a full purge is required.
Open docs/modules/ROOT/pages/snippets.adoc to inspect every adaptation snippet.
Long patch bodies are kept in docs/modules/ROOT/attachments/patches/ and included from the Antora page.
For recurring upstream updates, validation, and fork pushes, follow docs/modules/ROOT/pages/maintenance-workflow.adoc first.
docs/modules/ROOT/pages/adapter-workflow.adoc and docs/modules/ROOT/attachments/feature-matrix.json remain historical automation reference and feature-matrix material.