Codex++ Comprehensive Developer Manual

Welcome to the official developer documentation for Codex++. This document serves as the authoritative guide for building, extending, configuring, and deploying the Codex++ environment. It contains all the necessary implementation models, protocol standards, and architectural blueprints for advanced integration.

1. Introduction

In modern developer environments, AI coding assistants have transitioned from simple text completions to autonomous agents capable of performing complex code updates across multi-file codebases. One such desktop application is the Codex App. While the application provides robust context aggregation and interaction models, its design remains constrained within a closed Electron browser package. Developers are often unable to customize its user experience, establish automatic session backup workflows, inject custom editor utilities, or maintain continuous access to chats after migrating between backend AI model relays.

Codex++ is designed specifically to solve these constraints. It is an external launcher ecosystem that operates completely beside the Codex App process. By leverage native browser debugging pipelines, Codex++ unlocks premium, modular interface enhancements (such as Workspace Timelines, SQLite rollback backups, custom User Script evaluation, and Cloud Provider synchronization) without modifying a single byte of the original application installation binary.

2. What is Codex++

Codex++ is a premium external bootstrap launcher and manager tool configured for the desktop clients of Codex App. Historically developed as a Python-based utility (`codex-session-delete`), the platform has been fully redesigned as a compiled high-performance Rust workspace leveraging Tauri 2.x for administrative management controls.

The core concept of Codex++ centers around Dynamic Non-Invasive Extension (DNIE). Unlike traditional software modifications (which edit JavaScript files inside target app packages, leading to code signature corruption, broken updates, and security alert triggers), Codex++ boots the target application with standard Chromium remote debugging flags. It connects to the exposed debugging target via the native WebSocket protocol and pushes the frontend adjustments directly into the web application execution runtime context. This keeps configuration data independent of client versions, preserving user settings and allowing seamless side-by-side execution.

3. Core Features

The platform exposes a highly organized set of capabilities designed to optimize daily developer velocity:

• Dual Process Architecture: A no-window silent startup binary handles the injection loopback background tasks, while a graphical Tauri console offers diagnostics, shortcut configuration, and version updates.
• SQLite Database Syncing: Real-time tracking of workspace rows lets users roll back accidental file mutations or session removals via transactional SQL pipelines.
• Custom API Relays Support: Integrates directly with mainstream大模型 relays (like JOJO Code, AIGoCode, APIKEY.FUN, RunAPI, and Cubence) to sync active models, rollout metadata parameters, and database schemas.
• User Scripts Directory: Exposes dynamic hooks that read external Javascript files directly from configuration paths, running them inside the browser page frame.
• Workspace Timeline Overlay: Renders a visual sidebar timeline detailing chat history milestones, supporting single-click rollback states.

4. Installation

Codex++ provides compiled installation packages matching the underlying target operating system architecture. Download the latest binary releases directly from the project release system:

4.1 Windows Deployment

For Windows systems (x64 architectures), the installer registers execution shortcuts, creates data folders, and resolves helper ports:

1. Download the setup binary: CodexPlusPlus-*-windows-x64-setup.exe.
2. Execute the installer. It will automatically check for an existing Codex App installation inside default system directories (e.g., %PROGRAMFILES%/Codex or %LOCALAPPDATA%/Programs/Codex).
3. The setup process creates two separate start menu and desktop shortcuts:
   • Codex++: The silent launcher. Starts the app with background injection.
   • Codex++ Manager: The Tauri configuration panel.

4.2 macOS Deployment

Select the DMG package matching your system processor architecture to avoid execution layer emulation overhead:

• Apple Silicon (M1/M2/M3/M4): Download CodexPlusPlus-*-macos-arm64.dmg.
• Intel Processor: Download CodexPlusPlus-*-macos-x64.dmg.

Mount the DMG archive, drag both Codex++.app and Codex++ 管理工具.app (Codex++ Manager) directly into your local /Applications directory. On launch, the system may trigger macOS quarantine settings. See the Troubleshooting section below to bypass security blocks.

5. Configuration

Codex++ configuration settings are persisted in JSON format within the platform's user config paths. The environment parses these configurations to set active plugins, model synchronization states, and user script lists.

5.1 Configuration Paths

The configuration file structures are allocated within the following absolute user-level directories:

5.2 JSON Config Schemas

The following parameters define the structure of settings.json. Unmapped parameters default to baseline values on startup:

{
  "providerSyncEnabled": true,
  "debugPort": 9222,
  "helperPort": 18451,
  "autoUpdateEnabled": true,
  "backupLimit": 20,
  "customRelayUrl": "https://jojocode.com/v1"
}

Similarly, the script engine configuration (user_scripts.json) handles script permissions individually:

{
  "enabled": true,
  "scripts": {
    "builtin:timeline-history.js": true,
    "user:auto-formatter.js": true,
    "user:custom-shortcuts.js": false
  }
}

6. Architecture

The codebase is organized as a Rust workspace to guarantee modular development, low memory usage, and strict compiler optimization targets.

The workspace includes the following crates:

• codex-plus-core: The base logic library. Manages local path resolution, loopback debugging port verification, target Chromium DevTools Protocol (CDP) WebSocket attachments, bridge initialization, and request routing patterns.
• codex-plus-data: Database interface. Directly targets local SQLite databases (db.sqlite) inside Codex's state directory. Handles transactional table reads, backup creation, conversation deletions, workspace tracking, and cloud model syncing.
• codex-plus-launcher: The silent executable launcher binary. Resolves app paths, starts Codex App with remote debugging flags, executes initial injections, and runs in the background.
• codex-plus-tauri: The visible graphical configuration control panel. Contains setting controls, diagnostic reporting screens, file path selectors, updates checkers, and manual launch bindings.
• renderer-inject.js: The core injection script context. Injected directly into the target client frame on WebSocket handshake to render the custom extension overlay controls.

7. Enhancement Engine

The enhancement engine coordinates real-time interaction between Codex++ and the active chat browser targets. The core loopback communication maps to the following model:

7.1 WebSocket Attachment Handshake

When started, codex-plus-launcher executes Codex App with command-line flags pointing browser processes to a local loopback port:

Codex.exe --remote-debugging-port=9222 --remote-allow-origins=http://localhost:9222

The launcher then queries the debugging metadata endpoint http://localhost:9222/json/list using a HTTP GET call. This returns a JSON array listing active Chromium targets. Once the main app execution target is found, a connection is established using WebSocket client configurations: ws://localhost:9222/devtools/page/{target_id}.

7.2 Script Injection Logic

Once connected, the engine executes injection via the Chromium DevTools Protocol method Page.enable and runs script integration commands using Runtime.evaluate. This loads the local renderer-inject.js asset file directly within the execution frame context, avoiding any direct modification of source files.

8. User Scripts

User scripts allow developers to expand Codex++ behavior using standard JavaScript files. User scripts execute directly within the page context and gain access to the secure core bridge for database operations, custom styling overlays, and network relays.

8.1 Extension Script Template

Create a JavaScript file inside the user scripts folder. Below is a standard template for integrating custom hooks:

/**
 * Name: Custom Auto-Formatter
 * Description: Automatically formats code blocks in the chat window.
 * Author: Developer
 */
(function() {
  console.log('[User Script] Auto-Formatter Initialized.');

  // Bind keydown shortcut events
  window.addEventListener('keydown', (e) => {
    if (e.ctrlKey && e.key === 'f') {
      e.preventDefault();
      formatCodeBlocks();
    }
  });

  function formatCodeBlocks() {
    const codeBlocks = document.querySelectorAll('pre code');
    codeBlocks.forEach(block => {
      block.style.borderColor = '#00d4ff';
      block.style.boxShadow = '0 0 10px rgba(0, 212, 255, 0.2)';
    });
    console.log('[User Script] Formatted active code displays.');
  }
})();

8.2 Lifecycle & Execution Sequence

On launcher startup, the Rust backend executes the following cycle:

1. Scans built-in paths and the user scripts directory for valid *.js files.
2. Loads the script enablement configuration from user_scripts.json.
3. Reads files sequentially, wraps them in custom exception handlers to prevent page crashes, and pushes them through the WebSocket connection target.
4. Exposes an extension API menu inside the chat window for easy settings toggling.

9. Workflow

The runtime launch sequence coordinates settings alignment, process management, database verification, and injection hooks:

1. Booting Launcher: The user clicks the Codex++ shortcut. The background daemon runs.
2. Resolving Directories: Resolves target paths and settings data.
3. Syncing Providers: If Provider Sync is enabled, the backend reads configuration values and updates SQLite rows to match.
4. Executing Codex: Spawns Codex App processes using remote debugging flags.
5. Attaching Debugger: Listens for active ports, resolves WebSockets, and attaches targets.
6. Running Injection: Pushes renderer-inject.js and enabled user scripts to the page.
7. Background Watcher: Stays active to capture and route bridge actions until the target application is closed.

10. Best Practices

Keep operations clean and avoid database corruption by adhering to the following rules:

• Safe Updates: Let Codex update normally. Codex++ uses dynamic targets and remains compatible across minor updates.
• Transaction Backups: Set your backup threshold in settings (e.g., 20) to ensure your local history is preserved if database structures change.
• Script Auditing: Check third-party scripts before adding them to your user scripts directory to avoid secure credential leaks.
• Lock Resolution: Close any other terminal sessions running on port 9222 before starting Codex++ to prevent connection conflicts.

11. Security Specs

Codex++ is designed with security-first parameters, ensuring isolated and transparent execution:

• Dynamic Script Sandboxing: Injected code runs in the Electron renderer context, inheriting browser sandbox controls. It has no direct access to system shell commands or system files unless passed through the secure core Rust bridge.
• SQLite Transaction Safety: Every database operation (deleting, undoing actions, exporting) is executed via SQL transactions. If an operation fails, the transaction is rolled back completely to prevent data corruption.
• No Core Modification: It does not alter official app signatures, preventing security alerts or account flagging.

12. Performance Stats

The migration from Python to Rust has significantly optimized resource consumption, making Codex++ extremely lightweight:

13. FAQ Details

13.1 Does Codex++ send my code context or API keys to external servers?

No. Codex++ operates entirely offline on your local machine. All database backups, user scripts, and configuration directories remain locally inside your user profile. The only outgoing requests are those initiated by Codex itself to your configured AI relay endpoints.

13.2 How do I configure JOJO Code as my model relay?

Open the Codex++ Manager GUI panel, navigate to the Relays config block, toggle "Provider Sync" to active, and specify https://jojocode.com/v1 inside the custom relay endpoint address. Click save to apply configurations to your next launch session.

13.3 Can I load multiple custom script folder layouts?

The platform currently loads scripts from two specific directories: the built-in plugins folder and the user-level config scripts path. You can customize active extensions by enabling or disabling them inside the Manager GUI console.

14. Troubleshooting

If you encounter launch failures or unexpected behavior, follow this checklist to resolve path, lock, or quarantine blocks:

14.1 Loopback Debug Port Bind Conflict

Symptom: Launcher logs display: [Error] Failed to connect to remote target on port 9222. Connection refused.

Resolution: Another browser target or developer tool is currently using port 9222. You can check for port binds using standard commands:

# On Windows:
netstat -ano | findstr 9222

# On macOS:
lsof -i :9222

Close the conflicting process, or modify the debugPort parameter inside settings.json to use an open port (e.g., 9223).

14.2 macOS Gatekeeper Developer Verification Block

Symptom: macOS alert: "Codex++" cannot be opened because the developer cannot be verified.

Resolution: The binary lacks developer signatures. Force approval using macOS security controls:

1. Open System Settings ➔ Privacy & Security.
2. Scroll down to the Security section and locate the notice regarding Codex++.
3. Click "Open Anyway" to authenticate execution permissions.
4. Alternatively, authorize the app bundle via terminal command tools:

   xattr -cr "/Applications/Codex++.app"
   xattr -cr "/Applications/Codex++ 管理工具.app"

14.3 SQLite Database Busy Lock

Symptom: Logs indicate: [Data Error] Database is locked. Operation aborted.

Resolution: Codex App is currently running a background save transaction. Close Codex, wait 3 seconds, and start Codex++ again to clear database locks.

15. Conclusion

Codex++ provides a premium, non-invasive, and highly performant extension ecosystem for Codex App. By combining a Rust core silent launcher with a Tauri management dashboard, developers can safely customize their workflow, manage API relays, and extend features without code modification.

For feedback, bug reports, or queries, please reach out to our platform support team: 1727532@qq.com.