How the Codex Plugin Integrates with the Local Codex CLI: JSON-RPC Architecture Explained

The Codex plugin for Claude Code acts as a thin orchestration layer that delegates every AI operation to the local Codex CLI through a JSON-RPC app-server interface, automatically inheriting authentication and configuration while streaming real-time execution progress back to the editor.

The openai/codex-plugin-cc repository provides a bridge between Claude Code and OpenAI’s Codex CLI, transforming the command-line tool into a backend service for IDE-based workflows. Rather than implementing standalone AI logic, the plugin spawns the existing codex binary and communicates via structured JSON-RPC messages. This design ensures that model inference, sandboxing, and file operations remain handled by the local CLI while the plugin manages session state and UI updates.

Architecture Overview

The plugin operates as a JSON-RPC client that connects to the Codex CLI's app-server mode. No separate AI runtime or network service is required; the plugin simply launches the local binary and forwards responses to Claude Code. This architecture ensures that all heavy lifting—including token generation, permission management, and filesystem sandboxing—executes within the trusted local Codex environment.

Binary Detection and Availability Checks

Before initiating connections, the plugin verifies that the Codex CLI is installed and supports the required subcommands.

Verifying CLI Installation

In plugins/codex/scripts/lib/codex.mjs (lines 86-99), the binaryAvailable utility—imported from plugins/codex/scripts/lib/process.mjs—performs two validation steps:

• Confirms the codex binary exists and responds to --version
• Validates that the app-server subcommand is available via codex app-server --help

These checks prevent execution errors by ensuring compatibility before process spawning occurs.

Connecting to the App-Server

Once validation passes, the plugin establishes communication through the CodexAppServerClient class defined in plugins/codex/scripts/lib/app-server.mjs (lines 35-53).

Direct Mode vs. Shared Broker Mode

The client automatically selects between two connection strategies:

• Direct mode (SpawnedCodexAppServerClient): Spawns a dedicated codex app-server process for isolated task execution
• Shared mode (BrokerCodexAppServerClient): Connects to an existing broker socket when a persistent Codex runtime is already running, minimizing resource overhead

This dual-mode approach allows the plugin to either create fresh sessions or attach to long-lived Codex instances.

Thread and Turn Management

All plugin commands—including /codex:review, /codex:rescue, and /codex:turn—delegate to high-level wrappers in plugins/codex/scripts/lib/codex.mjs (lines 10-18 and 44-57).

The functions runAppServerReview, runAppServerTurn, and findLatestTaskThread translate IDE interactions into specific RPC method calls:

• thread/start: Creates a new Codex thread for reviews or interactive tasks
• review/start: Initializes a read-only code review session
• turn/start: Launches a task turn with a specific prompt, model, and sandbox configuration

Real-Time Progress Reporting

While the Codex process executes tasks, the plugin receives JSON-RPC notifications that drive live UI updates. The captureTurn function in plugins/codex/scripts/lib/codex.mjs (lines 61-89) handles incoming messages such as item/started, item/completed, and turn/completed.

These notifications are buffered until the turn ID is confirmed, then forwarded to Claude Code via the onProgress callback. This mechanism displays real-time status including "Running command", "Applying file changes", and reasoning summaries without polling the subprocess.

Authentication and Configuration Inheritance

Because the plugin utilizes the same Codex binary installed on the system, it automatically inherits all existing authentication and settings. The getCodexAuthStatus function (lines 25-33 in plugins/codex/scripts/lib/codex.mjs) queries the app-server for account data and configuration contexts.

This integration means the plugin respects:

• ChatGPT login sessions or API keys configured via the CLI
• Global settings in ~/.codex/config.toml
• Project-level overrides in .codex/config.toml

Session Import and Transfer

The plugin supports bidirectional workflow integration through session migration. The externalAgentSessionMigration and requestExternalAgentSessionImport functions (lines 81-89 and 101-110 in plugins/codex/scripts/lib/codex.mjs) package Claude Code conversation state and transmit it via the externalAgentConfig/import RPC method.

This allows seamless handoff of debugging sessions from Claude Code to the standalone Codex UI using codex resume <thread-id>.

Implementation Examples

Starting a Code Review

import { runAppServerReview } from "./plugins/codex/scripts/lib/codex.mjs";

await runAppServerReview(process.cwd(), {
  target: { type: "uncommitted" },
  threadName: "Codex Review: feature-branch",
  onProgress: (msg) => console.log(msg)
});

Launching a Task Turn

import { runAppServerTurn } from "./plugins/codex/scripts/lib/codex.mjs";

await runAppServerTurn(process.cwd(), {
  prompt: "Refactor the authentication middleware to use async/await",
  sandbox: "read-write",
  model: "gpt-4",
  onProgress: (msg) => console.log(msg)
});

Connecting to the App-Server

import { CodexAppServerClient } from "./plugins/codex/scripts/lib/app-server.mjs";

const client = await CodexAppServerClient.connect(process.cwd(), {
  reuseExistingBroker: true
});

await client.request("thread/start", {
  cwd: process.cwd(),
  sandbox: "read-only"
});

Summary

• The Codex plugin delegates all AI processing to the local codex CLI via JSON-RPC communication through the app-server interface.
• Binary availability checks in codex.mjs (lines 86-99) ensure the CLI is installed and compatible before spawning processes.
• The CodexAppServerClient in app-server.mjs (lines 35-53) supports both direct process spawning and shared broker connections for flexible resource management.
• All authentication and configuration automatically propagate from existing Codex CLI settings, requiring no duplicate setup.
• Real-time progress notifications stream back through handlers like captureTurn (lines 61-89), providing live execution updates.
• Session import capabilities via requestExternalAgentSessionImport enable seamless handoff between Claude Code and the standalone Codex CLI.

Frequently Asked Questions

Does the Codex plugin run its own AI model?

No. According to the openai/codex-plugin-cc source code, the plugin is strictly an orchestration layer that delegates every operation to the local Codex CLI binary. It spawns the CLI as a subprocess and communicates via JSON-RPC, meaning all model inference occurs within the Codex runtime rather than the plugin itself.

What happens if the Codex CLI is not installed?

The plugin performs strict availability checks using binaryAvailable("codex", ["--version"], ...) and binaryAvailable("codex", ["app-server", "--help"], ...) in plugins/codex/scripts/lib/codex.mjs (lines 86-99). If the binary is missing or lacks the required app-server subcommand, the plugin aborts with a clear error message before attempting to execute any commands.

How does the plugin handle authentication?

Authentication is inherited automatically from the Codex CLI configuration. The getCodexAuthStatus function (lines 25-33 in plugins/codex/scripts/lib/codex.mjs) queries the app-server for account data, respecting existing ChatGPT logins, API keys, and configuration files located at ~/.codex/config.toml or project-level .codex/config.toml directories.

Can I transfer a Claude Code session to the Codex CLI?

Yes. The plugin implements session migration through requestExternalAgentSessionImport (lines 101-110 in codex.mjs), which transmits conversation state via the externalAgentConfig/import RPC method. After migration, you can resume the thread in the standalone Codex CLI using codex resume <thread-id>, maintaining full context across tools.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}