Codex++ Linux

Codex++ Linux is an unofficial Linux installer and launcher for the OpenAI Codex desktop app experience with Codex++ tweaks enabled.

It packages the Linux setup into a normal desktop app: an installable .deb, a launcher icon, a Cinnamon panel favorite on Linux Mint, terminal commands, health checks, logs, repair commands, and a bundled Linux badge tweak inside the Codex UI.

This project is unofficial. It is not affiliated with OpenAI, b-nnett, Codex++, or better-slop.

What This Does

Codex++ Linux glues together three upstream projects:

• OpenAI Codex: the Codex CLI and local app-server runtime.
• Codex++: the tweak system that patches the Codex desktop app and loads user tweaks.
• codex-app-linux: the unofficial Linux desktop shell and packaging bridge for the Codex app.

Upstream Sync

Codex++ Linux tracks Codex++ as an upstream dependency and inspiration, not as a Git fork. The repositories have unrelated histories: this project owns the Linux packaging, launcher, diagnostics, and desktop integration layer, while b-nnett/codex-plusplus owns the tweak system.

Latest upstream check:

• Upstream: b-nnett/codex-plusplus
• Branch: main
• Checked ref: f98e7e9 (Merge codex/1.0.0)
• Checked on: 2026-06-07

For future syncs, fetch upstream and review Codex++ changes against the wrapper behavior before updating docs, compatibility notes, or installer assumptions. Do not merge unrelated upstream history into this package.

This repo adds the Linux user experience around those pieces:

• installable Debian package for Ubuntu, Debian, Linux Mint, Pop!_OS, Zorin, and similar distributions
• Codex++ Linux desktop launcher
• panel pinning for Cinnamon/Linux Mint
• installed icon assets
• bundled Codex Linux Badge tweak that shows a Linux badge inside the Codex app and on the Codex++ tweaks page
• codex-plusplus-linux and codex++ terminal commands
• first-run install, launch, repair, logs, and doctor commands
• per-user logs under ~/.local/share/codex-plusplus-linux

Screenshots

Add screenshots before publishing the first release:

• app menu entry for Codex++ Linux
• Cinnamon panel icon
• first app launch
• Codex++ tweaks/settings screen
• bundled Linux badge inside Codex

Suggested paths:

docs/screenshots/menu.png
docs/screenshots/panel.png
docs/screenshots/app.png

Supported Systems

Tested target:

• Linux Mint 22.1 Cinnamon
• Linux x86_64
• Node.js 20+

Expected to work on:

• Ubuntu 24.04+
• Debian-based distributions with Node.js 20+
• other x86_64 Linux desktops that support freedesktop .desktop launchers

Not currently supported:

• ARM Linux
• Flatpak/Snap packaging
• AppImage packaging
• Wayland-specific fixes beyond what upstream Electron/Codex support

Install From The .deb

Download the latest .deb from GitHub Releases, then install it:

sudo apt install ./codex-plusplus-linux_0.2.0_amd64.deb

Then run:

codex-plusplus-linux install

Open the app from your launcher:

Codex++ Linux

On Cinnamon/Linux Mint, the installer also tries to pin Codex++ Linux to the bottom panel favorites.

The installer also adds a bundled Codex++ tweak named Codex Linux Badge. It places a small Linux badge near the Codex app controls when the UI is available, and adds a visible Linux identity row inside the Codex++ tweaks/settings UI.

Install From Source

git clone https://github.com/davidpavlovschi/codex-plusplus-linux.git
cd codex-plusplus-linux
npm install
npm install -g .
codex-plusplus-linux install

Replace the GitHub owner if you publish under a different account or organization.

Build The .deb

npm install
scripts/build-deb.sh

The package is written to:

dist/codex-plusplus-linux_0.2.0_amd64.deb

Use The App

Launch from the desktop:

Codex++ Linux

Launch from terminal:

codex-plusplus-linux launch

Short alias:

codex++ launch

Right-Edge Panel API

Codex++ Linux includes a local daemon for panels, launchers, and desktop widgets:

codex-plusplus-linux daemon

The Debian package installs a user systemd service:

systemctl --user status codex-plusplus-linux-daemon.service

Panel JSON endpoints:

http://127.0.0.1:17654/status
http://127.0.0.1:17654/usage
http://127.0.0.1:17654/health
http://127.0.0.1:17654/active-window

CLI equivalent:

codex-plusplus-linux status-json
codex-plusplus-linux usage

The status payload includes health, recent git projects, recent Codex sessions, available actions, and local token usage with an API-equivalent USD estimate. The estimate is not ChatGPT/Codex subscription billing; it is a local calculation using OpenAI API token prices.

Project launcher:

codex-here
codex-plusplus-linux open /path/to/project

Nemo File Manager Actions

Install optional Nemo context-menu actions for Linux Mint/Cinnamon from a source checkout:

integrations/nemo/install.sh

Or from the Debian package install:

/opt/codex-plusplus-linux/integrations/nemo/install.sh

The actions are installed to ~/.local/share/nemo/actions and add:

• Open folder in Codex
• Ask Codex about this file
• Explain this error log
• Generate README for this folder

Restart Nemo if they do not appear immediately:

nemo -q

Health Check

codex-plusplus-linux doctor

The doctor checks:

• Node.js, npm, and tar
• bundled Codex CLI
• codex-app-linux
• downloaded Codex desktop shell
• desktop launcher and icon
• bundled Linux badge tweak
• Codex++ patch state
• Codex++ watcher state

Logs

Print log locations:

codex-plusplus-linux logs

Main launcher log:

~/.local/share/codex-plusplus-linux/logs/launcher/latest.log

Codex++ runtime logs:

~/.local/share/codex-plusplus/log/main.log
~/.local/share/codex-plusplus/log/preload.log

Watcher logs:

journalctl --user -u codex-plusplus-watcher.service -n 100 --no-pager

Repair

If a Codex app update removes the patch or the tweaks disappear:

codex-plusplus-linux repair

Codex++ also installs a watcher that normally reapplies the patch automatically.

Uninstall

Remove the desktop integration and ask Codex++ to uninstall its patch:

codex-plusplus-linux uninstall

Remove the Debian package:

sudo apt remove codex-plusplus-linux

If installed globally through npm:

npm uninstall -g codex-plusplus-linux

This does not delete your OpenAI/Codex account data, Codex CLI config, or unrelated ~/.codex files.

Important Paths

Wrapper state:

~/.local/share/codex-plusplus-linux

Codex++ data and tweaks:

~/.local/share/codex-plusplus
~/.local/share/codex-plusplus/tweaks

Downloaded Linux desktop bundle:

~/.cache/codex-app-linux/<version>/linux-unpacked

System package install:

/opt/codex-plusplus-linux
/usr/bin/codex-plusplus-linux
/usr/share/applications/codex-plusplus-linux.desktop
/usr/share/icons/hicolor

Current Linux Notes

This installer disables Codex++ self-update in:

~/.local/share/codex-plusplus/config.json

The Codex++ repair watcher remains enabled. Self-update is disabled because the upstream updater can fail on Linux when moving staged updates from /tmp into $HOME across filesystems. Repairing the app patch still works.

The desktop shell may print GTK/appmenu warnings, Electron protocol-handler warnings, or unsupported feature messages. Those are currently non-fatal. The important checks are codex-plusplus-linux doctor and the launcher log showing Codex CLI initialized.

Credits

This project exists because of upstream work:

• OpenAI for openai/codex, the Codex CLI and app-server runtime used by the desktop app.
• b-nnett and contributors for codex-plusplus, the tweak system that makes the Codex desktop app extensible.
• better-slop and contributors for codex-app-linux, the unofficial Linux Codex app packaging bridge.
• The Linux desktop ecosystem: freedesktop.org launchers, Debian packaging, hicolor icons, systemd user services, and Cinnamon/Linux Mint panel integration.

Authors

• Doved, project owner and Linux packaging maintainer.
• OpenAI Codex, co-authoring assistant for the initial Linux wrapper, docs, packaging, and validation work.

Follow Doved on X: @real_doved

Legal

Codex++ Linux is a wrapper/installer. It does not claim ownership of OpenAI Codex, Codex++, or codex-app-linux.

OpenAI, Codex, and related marks belong to their respective owners. This project is unofficial and provided without warranty. Use it at your own risk.

See ACKNOWLEDGEMENTS.md for detailed upstream citations.

License

MIT. See LICENSE.