Advanced Addons Codex Bridge

Local companion for Advanced Addons Pro. It runs the pinned Codex app-server over JSONL stdio and exposes an origin-bound, loopback-only WSS endpoint to the Gutenberg and Elementor editors.

This package is distributed as a normal npm CLI package.

Requirements

• Node.js 20 or newer (no system OpenSSL install required).
• Advanced Addons Pro with the Codex Agent editor integration enabled.
• A local browser session that can access the WordPress editor.

Install

npm install -g @advanced-addons/codex-bridge

You can also run the package without a global install:

npx -y @advanced-addons/codex-bridge start

Start the Bridge

advanced-addons-codex start

On its first run, start creates and trusts a per-install localhost certificate so the WordPress editor can connect securely to the loopback bridge. Later starts reuse it. The separate install command remains available to repair the certificate trust entry if needed.

start prints a single-use pairing code that expires after ten minutes.

Open a Gutenberg or Elementor editor, select Codex Agent (Beta) in the Advanced Addons chat header, enter the pairing code in the inline pairing card, then choose Sign in with ChatGPT.

By default, the bridge uses an isolated Codex home. ChatGPT credentials stay in the bridge's own runtime directory, and the user's normal Codex configuration, MCP servers, and skills are not loaded.

Shared Codex Mode

To reuse the normal Codex login, MCP configuration, and enabled skills, start the bridge explicitly in shared mode:

advanced-addons-codex start --share-codex-home

If the bridge is already running, stop it before changing modes.

Shared mode loads enabled skills through the Codex app-server and can inherit external MCP servers from the normal Codex configuration. Tools annotated read-only can run automatically, while unannotated and write-capable tools ask every time and offer only Deny or Allow once. Configure MCP servers and complete OAuth in the Codex app or CLI before starting the bridge.

Same-origin HTTP MCP servers for the active WordPress site are disabled inside Gutenberg and Elementor bridge sessions so they cannot bypass the post- and session-bound editor tools. Shell commands, filesystem writes, web search, hooks, apps, and multi-agent tools remain disabled. Because external MCP servers execute outside the bridge filesystem sandbox, use shared mode only when you trust the configured servers.

Status and Stop

Check the bridge:

advanced-addons-codex status

Check the installed bridge version:

advanced-addons-codex --version

Stop the bridge:

advanced-addons-codex stop

Runtime state is stored under ~/.advanced-addons/codex-bridge by default. Set ADVANCED_ADDONS_CODEX_HOME to use a different location.

Visual-reproduction references and browser capture variants are kept locally for auditing under ~/.advanced-addons/codex-bridge/captures. Locate them with advanced-addons-codex captures, or print only the newest run with advanced-addons-codex captures --latest. The archive is private, retains at most 20 runs and 250 MB, and is never forwarded to Codex; only the chosen capture is model-visible.

Updating

Install the latest published version:

npm install -g @advanced-addons/codex-bridge@latest

Then restart the bridge:

advanced-addons-codex stop
advanced-addons-codex start

Bridge protocol 1.15 adds runtime-aware Codex discovery metadata and model-catalog refresh support. Protocol 1.14 adds automatic full-page versus visible-viewport selection, locks the chosen scope, uses reference-shaped multi-scale calibrated comparison with bounded alignment, reports target geometry, and saves bounded local debug evidence. Scores are intentionally not comparable with protocol 1.13. Protocol 1.13 added ranked spatial hotspots, aspect and dimension evidence, and pass-to-pass trends. Generated-image activity remains reduced to compact IDs, status, dimensions/MIME when available, and upload availability; image bytes and local paths stay out of visible events, approval arguments, and restored editor history. The bridge transfers only registered generated or attached images, validates their bytes, and keeps encoded payloads in hidden execution arguments. Capture normalizes Tailwind CSS Color 4 values such as oklab() and oklch() for the screenshot renderer, then returns one directly forwardable chosen image plus compact comparison evidence through the app-server image channel. Only conversations created by Advanced Addons for the current site, WordPress user, editor, and post are exposed. Conversations created with an older editor toolset remain available in history; continuing one starts a fresh compatible conversation.

Bridge 0.8.20 prefers a supported Codex CLI discovered through ADVANCED_ADDONS_CODEX_BIN or PATH, reports the active runtime version/source, and refreshes the WordPress model catalog after reconnecting and every five minutes. Bridge 0.8.19 introduced calibrated automatic-scope visual verification and local capture auditing. Bridge 0.8.18 added ranked 4×4 spatial mismatch hotspots, pass-to-pass score and regional trends, aspect/dimension diagnostics, and five eligible passes. Bridge 0.8.16 replaced native goal mode with session-bound, bridge-controlled visual refinement. It forwards authoritative score evidence to Codex, locks acceptance state, requires a successful mutation before each eligible capture, and stops after the configured pass cap or two stalled continuations. Protocol major remains exact; the bundled Codex version is the minimum supported fallback rather than an exact runtime requirement.

Compatibility uses the plugin's minimum bridge version, exact protocol major, and minimum supported Codex version. Set ADVANCED_ADDONS_CODEX_BIN when the preferred CLI is not discoverable on PATH; the bridge falls back to its bundled runtime when no supported installed CLI is available. Keep the default isolated Codex home, or pass --share-codex-home explicitly when the bridge should reuse the CLI's existing login and configuration. Raise the WordPress bridgeVersion floor only when a plugin release requires newer bridge behavior. Bridge package versions may advance independently as long as they stay at or above that floor.

The bridge requires Node.js 20 or newer and follows the official Codex app-server protocol.