CodexBridge

CodexBridge is a gateway designed to connect multiple chat platforms to a single shared Codex engine. It allows users to switch backend provider profiles within Codex while maintaining a consistent interface across different platforms.

Core Mental Model:

• Platforms as Adapters: Chat platforms (like WeChat) act as adapters to the bridge.
• Codex as Execution Engine: Codex serves as the central engine for processing.
• Thread State as Source of Truth: The Codex thread state remains the authoritative source for conversation context.

As of the current roadmap, active package-level development is intentionally on hold. The following packages are in a paused state:

• @codexbridge/codex-gateway: Paused (focusing on protocol work).
• @codexbridge/mission-control: Paused (focusing on orchestration work).
• codex-native-api: Retained for possible future work, but currently paused.

Development will resume once the bridge direction is further narrowed.

CodexBridge is a multi-layered system designed to bridge platform-specific messaging (like WeChat or Telegram) with the Codex engine. It consists of three main components:

1. Platform Plugins: Handle inbound/outbound messaging and platform-specific events (e.g., WeChat, Telegram).
2. Codex Engine Adapter: Wraps the Codex app-server runtime to manage threads and models.
3. Bridge Core: The central logic that maps platform scopes to canonical Codex sessions.

The primary goal is to expose Codex capabilities through platforms like WeChat while allowing the engine to connect to various provider profiles (e.g., OpenAI, DeepSeek, Gemini) via @codexbridge/codex-gateway.

The current version of the Web Console provides the following capabilities:

• Session Management: View a list of sessions and detailed session information, including bindings, automations, and related assistant records.
• Automation Management: View a list of configured automations.
• System Monitoring: View runtime status.
• Data Access: Access read-only JSON APIs.

Note: This version does not yet support browser-side message sending or websocket streaming.

The Codex Native API is a localhost-first API designed to expose the logged-in Codex runtime state as a set of standard endpoints. It allows for isolated execution of tasks (like intent classification or side reasoning) without polluting the main user-visible chat thread.

Key architectural principles:

• Localhost by default: It binds to localhost and uses local auth/shared-secret policies.
• Native-first routing: The main chat flow remains unchanged, while side tasks prefer the native API. External providers serve only as a fallback.
• Isolation: It uses proven native isolated execution primitives to ensure tasks do not interfere with the active bridge session history.
• Continuity: It maps Codex-native thread/turn semantics to standard response_id and previous_response_id patterns.

The /auto command skill is used to manage scheduled automation jobs via natural language.

Key Principles:

• Separation of Concerns: Codex (the AI) interprets natural language and returns structured JSON, but Bridge is the only component that actually creates, updates, pauses, resumes, deletes, or persists jobs.
• Safety First: Codex must never perform destructive actions directly. All mutating actions (create, update, delete, pause, resume, rename) must return requiresConfirmation: true to ensure the user confirms the change via the Bridge interface.
• Structured Output: Codex must only return JSON following the codexbridge.auto-command-skill.v1 schema.

The Codex Native API is a localhost-callable API surface that exposes the capabilities of a logged-in local Codex app-server.

Its primary purpose is to provide an isolated execution environment for lightweight, side-task reasoning without polluting the main CodexBridge conversation thread (e.g., WeChat or Telegram). This allows the main chat flow to remain unchanged while offloading specific tasks to the native API.

Key Use Cases:

• Classification
• Intent detection
• Normalization
• Short verification
• Lightweight side reasoning
• Providing a standard API surface for external local clients

Core Responsibilities:

• Localhost API exposure over the logged-in Codex app-server.
• Responses-first request/response routing.
• response_id / continuation mapping to emulate stateless API calls.
• Local authentication, binding, and safety rules.

The @codexbridge/codex-gateway package is a protocol layer designed to allow Codex to run on non-OpenAI and OpenAI-compatible model providers. It translates Codex-native Responses API traffic into provider-specific APIs.

Core Responsibilities:

• Request and response conversion (Responses and Chat Completions).
• SSE and stream event conversion.
• Tool/function call conversion.
• Usage and error normalization.
• Multimodal and reasoning/thinking payload policy.
• Provider capability and payload rules.
• Providing a local Responses adapter server with /responses and /v1/responses compatibility routes.

CodexBridge uses specific directories for state and configuration:

• State directory: ~/.codexbridge
• WeChat account files: ~/.codexbridge/weixin/accounts/
• Serve lock file: ~/.codexbridge/runtime/weixin-serve.lock
• Default Codex auth path: ~/.codex/auth.json
• Default Codex instructions path: ~/.codex/AGENTS.md

WeChat Runtime Checklist:

1. Run npm run weixin:login.
2. Confirm the account file exists in ~/.codexbridge/weixin/accounts/.
3. Start the loop with npm run weixin:serve.
4. Send /h or /status from WeChat to verify connectivity.

Mission Control provides a supervision foundation to manage mission lifecycles and recover from failures.

Mission States

Missions transition through the following supervisable states:

• queued
• planning
• running
• verifying
• repairing
• idle (terminal state)

Paused States

Certain states require explicit host control actions (like resume or retry) and are not automatically resumed by supervision:

• waiting_user
• needs_human
• handoff

Supervision Capabilities

The supervision layer can:

• Recover stale leases.
• Rebuild status snapshots from repository truth.
• Sequentially dispatch missions.
• Detect loop-budget exhaustion (e.g., max_loops_reached) by reading CycleResult history.
• Refresh pristine source-backed missions via a package-owned source-sync command to align queued source metadata without manual patching of records.

The /review command skill is a read-only code-review mechanism. It allows Codex to interpret natural-language requests and normalize them into structured review targets for Bridge to execute.

Key constraints:

• It is read-only; it does not perform code changes.
• Codex classifies the intent and selects a target, but Bridge is the only component that executes the actual review.
• The response must be a single JSON object. Do not use Markdown, prose, or code fences in the response.