Imported from reason-machines/codex-skills (skills/codexplusplus-launcher/SKILL.md). Install upstream with npx skills add reason-machines/codex-skills --skill codexplusplus-launcher. Copyright stays with the author.

Codex++ Launcher Skill

Skill by ara.so — Codex Skills collection.

Codex++ is an external enhancement launcher for Codex App that doesn't modify the original installation. It uses Chromium DevTools Protocol (CDP) to inject enhancement scripts that unlock plugins in API key mode, enable session deletion, export conversations to Markdown, sync provider sessions, and add a timeline view.

Installation

Windows

Quick setup using batch script:

# Clone the repository
git clone https://github.com/BigPizzaV3/CodexPlusPlus.git
cd CodexPlusPlus

# Run setup.bat and select option [1]
setup.bat

Command line installation:

# Install dependencies
python -m pip install -e .

# Create shortcuts and uninstall entry
python -m codex_session_delete setup

# Launch Codex++
python -m codex_session_delete launch

After setup, double-click Codex++.lnk on the desktop to launch.

macOS

# Install
python -m pip install -e .

# Create /Applications/Codex++.app bundle
python -m codex_session_delete setup

# Launch from Applications or command line
python -m codex_session_delete launch

Key Commands

Launch and Setup

# Launch Codex++ (with CDP injection)
python -m codex_session_delete launch

# Launch with custom ports
python -m codex_session_delete launch --debug-port 9229 --helper-port 57321

# Launch with specific Codex installation
python -m codex_session_delete launch \
  --app-dir "C:/Program Files/WindowsApps/OpenAI.Codex_xxx/app"

# Install shortcuts/app bundle
python -m codex_session_delete setup

# Uninstall (keeps logs and backups)
python -m codex_session_delete remove

# Uninstall and remove all data
python -m codex_session_delete remove --remove-data

Updates

# Check for updates
python -m codex_session_delete check-update

# Update to latest version
python -m codex_session_delete update

Windows Auto-Watcher (Optional)

Automatically intercept Codex launches and use Codex++ instead:

# Install watcher
python -m codex_session_delete watch-install

# Remove watcher
python -m codex_session_delete watch-remove

# Temporarily disable watcher
python -m codex_session_delete watch-disable

# Re-enable watcher
python -m codex_session_delete watch-enable

Core Features

1. Plugin Unlock in API Key Mode

When using API Key authentication, Codex App normally disables plugin access. Codex++ unlocks this functionality.

How it works:

• Injects renderer-inject.js via CDP
• Patches frontend to enable plugin UI
• Allows force-installation of special plugins

2. Session Deletion

Codex natively only allows archiving. Codex++ adds true deletion with undo support.

Features:

• Delete button appears on hover in session list
• Confirmation dialog before deletion
• Undo capability via local backup
• SQLite database cleanup

Data locations:

# Main Codex database
~/.codex/state_5.sqlite

# Deletion backups
~/.codex-session-delete/backups/

3. Markdown Export

Export conversations with local rollout data and timestamps.

Access:

• Click Codex++ menu → Export conversation
• Exports current session to timestamped .md file

4. Provider Sync

Syncs session metadata when switching model providers to prevent conversation loss.

Enable in settings:

1. Click Codex++ menu
2. Open settings panel
3. Enable "Provider 同步" (Provider Sync)
4. Restart Codex++

What it syncs:

• Rollout files
• SQLite thread records
• Project path cache

Backup location:

~/.codex/backups_state/provider-sync/

5. Conversation Timeline

Shows a right-sidebar timeline of user questions with timestamps and summaries.

Usage:

• Automatically appears in conversation view
• Hover for message summary
• Click to jump to message

Configuration

Settings Panel

Access via Codex++ menu in the top menu bar.

Available settings:

• Enable/disable Provider Sync
• Configure auto-launch behavior
• View backend status (green/red indicator)
• Check version and updates

Environment Variables

# Set proxy for GitHub resource loading
export HTTP_PROXY="http://127.0.0.1:7897"
export HTTPS_PROXY="http://127.0.0.1:7897"

# Launch with proxy
python -m codex_session_delete launch

On Windows PowerShell:

$env:HTTP_PROXY="http://127.0.0.1:7897"
$env:HTTPS_PROXY="http://127.0.0.1:7897"
python -m codex_session_delete launch

Programmatic Launch

from codex_session_delete.launcher import launch_codex_with_cdp

# Launch with custom configuration
launch_codex_with_cdp(
    app_dir="C:/Program Files/WindowsApps/OpenAI.Codex_1.2024.xxx/app",
    debug_port=9229,
    helper_port=57321,
    user_data_dir=None  # Uses default Codex user data
)

Project Structure

codex_session_delete/
  cli.py                 # CLI entry point
  launcher.py            # Launch Codex with CDP injection
  cdp.py                 # CDP communication and bridge
  helper_server.py       # Local helper HTTP server
  storage_adapter.py     # SQLite deletion/undo operations
  provider_sync.py       # Provider metadata sync
  settings_store.py      # Settings persistence
  windows_installer.py   # Windows shortcuts and uninstaller
  macos_installer.py     # macOS app bundle generation
  watcher.py             # Windows auto-watcher (optional)
  inject/
    renderer-inject.js   # Frontend injection script
tests/                   # Test suite

Common Patterns

Custom Installation Path

# When Codex is installed in non-standard location
python -m codex_session_delete launch \
  --app-dir "/custom/path/to/Codex/app"

Proxy Configuration for GitHub Resources

# Auto-detection (tries common ports: 7890, 7897, 1080, 10809, 10908)
python -m codex_session_delete launch

# Manual proxy specification
export HTTP_PROXY="http://127.0.0.1:7897"
export HTTPS_PROXY="http://127.0.0.1:7897"
python -m codex_session_delete launch

Backup and Recovery

from codex_session_delete.storage_adapter import LocalStorageAdapter

adapter = LocalStorageAdapter()

# Delete a session (creates backup)
adapter.delete_session(session_id="abc123")

# Undo deletion (restores from backup)
adapter.undo_delete(session_id="abc123")

Provider Sync Automation

from codex_session_delete.provider_sync import ProviderSync

sync = ProviderSync()

# Sync before launch
sync.sync_all_providers()

Development

Setup Development Environment

# Clone repository
git clone https://github.com/BigPizzaV3/CodexPlusPlus.git
cd CodexPlusPlus

# Install with test dependencies
python -m pip install -e .[test]

# Run tests
python -m pytest -q

Testing CDP Injection

import asyncio
from codex_session_delete.cdp import CDPClient

async def test_injection():
    client = CDPClient(port=9229)
    await client.connect()
    
    # Inject custom script
    await client.inject_script("console.log('Test injection');")
    
    await client.close()

asyncio.run(test_injection())

Troubleshooting

Codex++ Doesn't Launch

Check logs:

# Windows
type %USERPROFILE%\.codex-session-delete\launcher.log

# macOS/Linux
cat ~/.codex-session-delete/launcher.log

Common issues:

• Codex App not installed
• Port 9229 already in use
• Python environment not accessible
• Codex path changed after update

Solution:

# Find Codex installation
# Windows: typically in %LOCALAPPDATA%\Programs or WindowsApps
# Specify path manually
python -m codex_session_delete launch --app-dir "path/to/Codex/app"

Codex++ Menu Not Appearing

Verify launch method:

• Must launch from Codex++ shortcut, not original Codex
• Check if Codex is running with --remote-debugging-port=9229

Check CDP connection:

# Should return JSON if CDP is active
curl http://127.0.0.1:9229/json

Plugin Loading Failed or GitHub Resource Errors

Cause: Network cannot reach GitHub directly.

Solutions:

# 1. Use system proxy (auto-detected)
python -m codex_session_delete launch

# 2. Specify proxy manually
export HTTP_PROXY="http://127.0.0.1:7897"
export HTTPS_PROXY="http://127.0.0.1:7897"
python -m codex_session_delete launch

# 3. Check proxy is running
curl --proxy http://127.0.0.1:7897 https://github.com

Sessions Disappear After Provider Switch

Enable Provider Sync:

1. Click Codex++ menu
2. Open settings panel
3. Enable "Provider 同步"
4. Restart Codex++

Manual sync:

python -m codex_session_delete launch  # Syncs on startup if enabled

Port Already in Use

# Use different ports
python -m codex_session_delete launch \
  --debug-port 9230 \
  --helper-port 57322

# Find what's using port 9229
# Windows
netstat -ano | findstr :9229

# macOS/Linux
lsof -i :9229

Watcher Not Working (Windows)

Check watcher status:

# View watcher log
type %USERPROFILE%\.codex-session-delete\watcher.log

# Reinstall watcher
python -m codex_session_delete watch-remove
python -m codex_session_delete watch-install

SQLite Database Locked

Cause: Codex is still running or file is locked.

Solution:

# Close Codex completely
taskkill /F /IM Codex.exe  # Windows
killall Codex              # macOS

# Then retry operation
python -m codex_session_delete launch

Data Locations Reference

# Codex main database
~/.codex/state_5.sqlite

# Session deletion backups
~/.codex-session-delete/backups/

# Provider sync backups
~/.codex/backups_state/provider-sync/

# Launch logs
~/.codex-session-delete/launcher.log

# Watcher logs (Windows only)
%USERPROFILE%\.codex-session-delete\watcher.log

# Settings
~/.codex-session-delete/settings.json

Security Notes

• Codex++ runs a local HTTP helper server (default port 57321)
• Only accepts connections from localhost by default
• Does not expose delete/undo endpoints to prevent accidental triggers
• All operations require CDP bridge authentication
• No modification of original Codex App files
• Backups are stored locally and not transmitted