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

> Understand how the Codex plugin integrates with the local Codex CLI via JSON-RPC. Learn how it delegates AI operations and streams progress back to your editor.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: internals
- Published: 2026-08-02

---

**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`](https://github.com/openai/codex-plugin-cc/blob/main/.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

```javascript
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

```javascript
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

```javascript
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`](https://github.com/openai/codex-plugin-cc/blob/main/.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.