Codex++

Codex++ is an external enhancement launcher for the Codex App. It does not modify the original Codex App installation. Instead, it launches Codex externally and injects enhancement scripts into the renderer process through the Chromium DevTools Protocol.

Table of Contents

• Current Features
• Problem
• Result
• Community
• Links
• How It Works
• Requirements
• Windows
  • Install or Uninstall from the Menu
  • Install from the Command Line
  • Uninstall from the Command Line
• macOS
  • Install
  • Uninstall
• Launch Directly
• Data and Backups
• Windows Auto-Takeover (Optional)
• FAQ
• Development
• Notes

Current Features

Current features:

• Show a Delete button when hovering over sessions in the list
• Confirm before deletion, with undo support
• Prefer server-side deletion and fall back to deleting local Codex SQLite session records when needed
• Add a Codex++ menu to the top menu bar
• Provide toggles for:
  • Plugin entry unlock
  • Force plugin install
  • Session deletion
• Support Windows shortcut install and uninstall
• Support generating /Applications/Codex++.app on macOS

Problem

In API key sign-in mode, the native Codex plugin entry prompts the user to sign in to ChatGPT, which prevents plugin features from being used normally:

At the same time, the native Codex session list only provides an archive action and does not include a real delete button:

Result

After launching Codex++, the plugin entry is unlocked and a delete button appears when hovering over sessions in the list:

A Codex++ item also appears in the top menu bar and opens the configuration panel when clicked:

Community

Scan the QR code below to join the Codex++ discussion group for bug reports, feedback, and feature suggestions:

Links

• LINUX DO

How It Works

Codex++ runs Codex through an external launcher:

1. Start the Codex App with:
   • --remote-debugging-port=9229
   • --remote-allow-origins=http://127.0.0.1:9229
2. Start a local helper service for delete and undo operations.
3. Inject renderer-inject.js through CDP.
4. Let the renderer communicate with the local helper through a CDP bridge so requests are not blocked by the page CSP.

This approach does not modify Codex app.asar and does not need to write DLLs into the Codex installation directory.

Requirements

• uv
• Windows or macOS
• Codex App installed

Install dependencies:

uv sync

Run tests:

uv sync --group dev
uv run --group dev pytest -q

Windows

Install or Uninstall from the Menu

Double-click:

setup.bat

Then choose:

[1] Install Codex++
[2] Uninstall Codex++
[3] Exit

Install from the Command Line

Run in the project directory:

uv run codex-session-delete setup

This creates:

Codex++.lnk

Double-click the shortcut to launch Codex++.

Uninstall from the Command Line

You can uninstall Codex++ from Windows Settings under Installed apps.

You can also run:

uv run codex-session-delete remove

To also remove Codex++ logs and backup data:

uv run codex-session-delete remove --remove-data

macOS

Install

uv run codex-session-delete setup

By default, Codex++ automatically looks for /Applications/Codex.app, /Applications/OpenAI Codex.app, or a Codex app under the user Applications directory, then creates:

/Applications/Codex++.app

Uninstall

uv run codex-session-delete remove

Launch Directly

If you do not want to install a shortcut, you can run:

uv run codex-session-delete launch

Common arguments:

uv run codex-session-delete launch \
  --app-dir "/Applications/OpenAI Codex.app" \
  --debug-port 9229 \
  --helper-port 57321

On Windows you can also specify the Codex install directory manually:

uv run codex-session-delete launch \
  --app-dir "C:/Program Files/WindowsApps/OpenAI.Codex_xxx/app" \
  --debug-port 9229 \
  --helper-port 57321

Data and Backups

Codex++ reads the local Codex database by default:

~/.codex/state_5.sqlite

Before deletion, related records are backed up to:

~/.codex-session-delete/backups

Hidden launch failure logs are written to:

~/.codex-session-delete/launcher.log

Windows Auto-Takeover (Optional)

By default, Codex++ only takes effect when you launch Codex from the Codex++ shortcut. If you start Codex directly from the Start menu, taskbar, or another native entry point, that launch will not be injected, and the Codex++ menu and plugin unlock features will not appear.

On Windows, you can register a background watcher to solve this. Every 3 seconds it checks the local CDP port. If Codex is running but CDP is not available, it terminates that batch of Codex processes and relaunches an injected version through the launcher. This allows Codex to be auto-taken over no matter where you open it from.

Trade-offs:

• When Codex is launched through a native path, it briefly opens once, gets terminated, and is relaunched through the launcher with CDP enabled. Visually this appears as a 1 to 2 second "open -> close -> reopen" flicker.
• The watcher stays resident through pythonw.exe and starts automatically at logon through both HKCU\...\Run and the Startup folder, which helps avoid interference from some registry cleanup tools.

Install

uv run codex-session-delete watch-install

The watcher starts immediately after installation. No reboot is required.

Uninstall

uv run codex-session-delete watch-remove

Running remove, or uninstalling Codex++ from the system, also triggers watch-remove automatically, so no extra cleanup is needed.

Temporary Toggle

Keep the auto-start registration but stop the watcher from taking over launches automatically:

uv run codex-session-delete watch-disable
uv run codex-session-delete watch-enable

Logs

%USERPROFILE%\.codex-session-delete\watcher.log

Example:

[...] watcher started (interval=3.0s)
[...] Codex running without CDP (pids=[...]); attempting takeover
[...] takeover: killing 4 codex pid(s): [...]
[...] takeover: CDP is up on 9229 (launcher pid=...)

FAQ

Double-clicking Codex++ does nothing

Check the log first:

%USERPROFILE%\.codex-session-delete\launcher.log

Common causes:

• Codex App is not installed or its path changed
• Port 9229 is already in use
• uv sync has not been run yet

The Codex++ menu does not appear

Make sure you launched Codex from the Codex++ shortcut rather than starting the original Codex app directly.

You can also confirm that Codex was started with the CDP argument:

--remote-debugging-port=9229

Uninstall fails on Windows

Update to the current version and reinstall once:

uv run codex-session-delete setup

The current version writes a stable uninstall entry and uses the absolute Python path from the project .venv for uninstall.

Development

Run tests:

uv run --group dev pytest -q

Project structure:

codex_session_delete/
  cli.py                 CLI entry
  launcher.py            Launch Codex and inject scripts
  cdp.py                 CDP communication and bridge
  helper_server.py       Local helper service
  storage_adapter.py     Local SQLite delete and undo
  windows_installer.py   Windows shortcuts and uninstall entries
  macos_installer.py     macOS app bundle install
  watcher.py             Optional Windows watcher for native launch takeover
  inject/renderer-inject.js

tests/                   Automated tests

Notes

Codex++ is an external enhancement tool and does not modify original Codex App files. If the Codex App updates and the page structure changes, the injected script may need to be updated as well.