Difference Between Shared and Direct Codex Runtime Modes in openai/codex-plugin-cc

Shared runtime mode delegates Codex execution to the plugin’s internal bridge and slash commands, while direct runtime mode bypasses the plugin entirely by invoking the codex binary manually from your terminal.

The openai/codex-plugin-cc repository integrates OpenAI Codex into Claude Code through two distinct execution strategies. Understanding the difference between shared and direct Codex runtime modes is essential for choosing between automated workflow orchestration and manual CLI control. While the plugin streamlines AI-assisted code reviews and rescues, it ultimately reuses your existing local Codex installation rather than spawning isolated runtime instances.

How Shared Runtime Mode Works

Shared runtime mode serves as the plugin’s default execution path, providing a structured bridge between Claude Code and your local Codex CLI.

The codex-cli-runtime Skill Contract

According to plugins/codex/skills/codex-cli-runtime/SKILL.md, the plugin implements a dedicated skill that defines the contract between Claude Code and the local Codex installation. This specification establishes the protocol for task submission, status polling, and result retrieval without creating separate runtime processes. The skill acts as a mediator that translates high-level intent into subprocess calls targeting your existing Codex binary.

Slash Command Interface and Background Execution

When you invoke commands such as /codex:review, /codex:adversarial-review, or /codex:rescue, the plugin routes these requests through plugins/codex/scripts/lib/codex.mjs. This module contains the logic that actually spawns the Codex CLI process, automatically inheriting your user- or project-level config.toml settings and authentication credentials. The plugin manages background execution, enabling you to check progress via /codex:status and retrieve final outputs via /codex:result.

# Initiate a background review using shared runtime

/codex:review --background

# Check execution status

/codex:status

# Retrieve the final result

/codex:result

How Direct Runtime Mode Works

Direct runtime mode bypasses the plugin’s mediation layer entirely, requiring you to manage Codex invocation manually.

Manual CLI Invocation

In direct mode, you interact with the Codex CLI explicitly from your terminal without plugin intervention. This approach provides full control over prompt construction, model selection, and execution parameters, but forfeits the plugin’s automated tracking capabilities.

# Run a task directly with explicit flags

codex task "Refactor the authentication module to use JWT" \
  --model gpt-4.1-mini --effort high --output ./results/auth-refactor.txt

# View the result manually

cat ./results/auth-refactor.txt

Configuration and Control Differences

Direct mode requires explicit specification of all overrides on the command line, as the plugin’s automatic configuration discovery does not apply. You must manually supply flags for model selection, effort levels, and output destinations, whereas shared mode automatically applies settings from your existing Codex configuration files.

Key Architectural Differences

• Execution Mediation: Shared mode routes commands through the codex-cli-runtime skill defined in plugins/codex/skills/codex-cli-runtime/SKILL.md, while direct mode invokes the binary without intermediaries.
• Process Ownership: Shared mode tasks are managed by the plugin’s internal logic in plugins/codex/scripts/lib/codex.mjs, enabling background execution and result caching. Direct mode spawns independent processes that operate outside the plugin’s visibility.
• Workflow Integration: The rescue agent documented in plugins/codex/agents/codex-rescue.md relies on shared mode to forward work through the plugin’s runtime bridge, whereas direct mode operates as a standalone terminal command.

Source Code Implementation Details

Skill Definition and Contracts

The shared runtime behavior is formally defined in plugins/codex/skills/codex-cli-runtime/SKILL.md. This document specifies the interface between Claude Code and the local Codex CLI, ensuring consistent execution across different environments while reusing the existing installation.

Script Execution Layer

The actual invocation logic resides in plugins/codex/scripts/lib/codex.mjs. This module translates slash commands into subprocess calls, handling authentication context and configuration file discovery automatically.

Agent Integration

As implemented in plugins/codex/agents/codex-rescue.md, the rescue agent leverages shared mode to orchestrate complex recovery workflows. This agent submits tasks through the plugin’s runtime bridge, allowing it to monitor progress and retrieve results through standardized commands rather than manual CLI calls.

Summary

• Shared runtime mode routes all Codex execution through the plugin’s codex-cli-runtime skill and slash commands, automatically managing configuration, authentication, and background task tracking.
• Direct runtime mode requires manual invocation of the codex binary with explicit flags, bypassing the plugin’s mediation layer and background processing capabilities.
• The plugin reuses your existing local Codex installation and configuration files rather than spawning isolated runtime instances, as documented in the README.md section "Does the plugin use a separate Codex runtime?".
• Background execution, status retrieval via /codex:status, and result fetching via /codex:result are exclusive to shared mode.

Frequently Asked Questions

Does the plugin create a separate Codex server?

No. According to the README.md in the openai/codex-plugin-cc repository, the plugin explicitly does not spin up a separate Codex runtime. Instead, it delegates execution to your local Codex CLI installation through the shared runtime mode, reusing your existing authentication and configuration.

Can I switch between shared and direct modes for the same task?

You cannot migrate a running task between modes. Tasks initiated through shared mode slash commands (/codex:review, etc.) are tracked by the plugin’s internal system and support status checking via /codex:status. Tasks started in direct mode run as independent terminal processes and must be monitored manually outside the plugin’s interface.

Where does shared mode read Codex configuration?

The plugin automatically picks up user-level and project-level config.toml settings that Codex uses. This logic is implemented in plugins/codex/scripts/lib/codex.mjs, which discovers and applies these settings when invoking the CLI on your behalf. Direct mode requires you to specify configuration overrides explicitly on the command line.

Which mode should I use for custom prompts?

Use direct runtime mode when you need full control over the prompt string, model selection, and effort levels via command-line flags. Use shared runtime mode for standardized workflows like code reviews (/codex:review), adversarial reviews (/codex:adversarial-review), and rescue operations (/codex:rescue) that benefit from the plugin’s background tracking and result retrieval capabilities.

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