Claude Code Codex Subagents

Claude Code plugin for OpenAI Codex subagents. Run Codex with GPT-6.1 Sol, Astra, or Luna, parallel code-review agents, and long-running Codex sessions from Claude Code through a daemonless Model Context Protocol (MCP) server.

claude-code-codex-subagents lets Claude Code delegate to Codex, an independent frontier model like Claude, for read-only code reviews, adversarial reviews, parallel codebase investigations, server/deployment checks, difficult debugging, native follow-ups, live steering, and explicit full-access Codex work when the user asks for it. If you are looking for a Claude Code Codex plugin, an OpenAI Codex MCP server, or Codex subagents for Claude, this is the integration.

Why Use It?

• Native Claude Code plugin workflow: Claude gets a small Task-like MCP surface: codex_task, codex_task_group, codex_followup, and codex_wait_any.
• OpenAI Codex second opinion: Codex gives Claude an independent frontier-model reviewer for adversarial checks and hard engineering work.
• Read-only by default: Codex starts with --sandbox read-only and non-interactive approvals.
• Daemonless MCP server: Claude launches the MCP server over stdio for the active session.
• Fast parallel review: Claude can launch several independent Codex agents with bounded concurrency.
• Current Codex models: Select GPT-6.1 Sol, Astra, or Luna with simple model aliases.
• Persistent sessions: App-server sessions keep Codex context across prompts and support live steering.
• Codex desktop friendly: The plugin prefers the Codex binary shipped inside Codex.app and creates normal Codex threads with task names for Desktop history.
• Debuggable: Verbose JSONL logging, diagnostics bundles, progress events, per-session resources, and recovery hints are built in.

Best For

• Claude Code users who want OpenAI Codex as a native-feeling subagent.
• Independent adversarial review before merging high-risk code.
• Parallel codebase analysis across API, tests, security, performance, docs, or deployment paths.
• Long-running Codex sessions that preserve context across follow-up prompts.
• Luna checks for focused technical tasks, with Sol and Astra for deeper work.
• Read-only-by-default delegation with explicit opt-in for full local Codex capabilities.

Quick Start

Requirements:

• Node.js 20 or newer
• Git (for marketplace downloads)
• Claude Code with plugin marketplace support
• Codex CLI installed and signed in, preferably through the Codex desktop app

Install Through Claude Code Marketplace

In a terminal, register this repository's marketplace and install the plugin for your user account:

claude plugin marketplace add xuio/claude-code-codex-subagents
claude plugin install codex-subagents@codex-subagents --scope user

Or, inside Claude Code:

/plugin marketplace add xuio/claude-code-codex-subagents
/plugin install codex-subagents@codex-subagents

Select Install for you if Claude Code opens the plugin details panel. You can also open /plugin, find the codex-subagents marketplace under Marketplaces, and install its codex-subagents entry from Discover.

The repository includes the built MCP server and skill. Marketplace installs need no npm install, build step, or manual MCP registration. Node.js and Codex must be available to Claude Code. Model availability depends on your Codex account.

Start a new Claude Code session after installation, then ask:

Use Codex to review this PR for correctness, security, and deployment risks.

To verify installation from the terminal:

claude plugin list

Look for codex-subagents@codex-subagents with enabled status. In a session, /plugin shows the installed plugin, and /mcp shows its codex-subagents server.

Update A Marketplace Install

claude plugin marketplace update codex-subagents
claude plugin update codex-subagents@codex-subagents --scope user

The new version loads in your next session. For automatic updates, open /plugin, select codex-subagents under Marketplaces, and enable auto-update.

If you previously used the local development installer, disable codex-subagents@codex-subagents-local in /plugin before enabling the marketplace copy, so Claude loads one copy of the MCP server.

This repository hosts its own marketplace. See the Claude Code marketplace documentation for marketplace and installation details.

Install From A Local Checkout

For local development or an editable install:

git clone https://github.com/xuio/claude-code-codex-subagents.git
cd claude-code-codex-subagents
npm run install:local

For plugin development, run Claude directly against this checkout without installing a package:

claude --plugin-dir .

For local development against Claude's installed plugin cache:

npm run dev:link
npm run dev:watch

dev:link symlinks Claude's local plugin install back to this working tree, so both Claude Code CLI and the Claude Desktop bundled Claude Code binary see your changes after dist/index.js is rebuilt.

Common Workflows

Ask One Codex Agent

Ask Codex for an adversarial second opinion on the session recovery code. Keep it read-only and return concrete findings with file paths.

Claude should use codex_task.

Run Parallel Codex Agents

Launch three Codex subagents in parallel: one for API behavior, one for tests, and one adversarial security reviewer. Keep all of them read-only.

Claude can call codex_task three times in parallel, or use codex_task_group when a single rolled-up response is useful.

Choose A Model

Use Codex with GPT-6.1 Sol to review the tool descriptions.

Claude can pass advanced.model: "sol" (or "codex") for gpt-6.1-sol, "astra" for gpt-6-astra, or "luna" for gpt-6-luna. Omit the model to inherit configuration. Spark is retired; saved Spark requests return a migration message. See model and reasoning options.

Keep A Codex Session Alive

Start a long-running Codex session on this repo, then let me send follow-up prompts into the same context.

Claude should use codex_task for the initial prompt, preserve the returned session_id, and use codex_followup to continue, steer, wait on, or cancel that same Codex context. For multiple background sessions, Claude should use codex_wait_any to harvest whichever finishes first. Clients can also subscribe to codex://sessions/{session_id} for milestone and completion updates. For a completed first turn, Claude should set keep_session: true; for long first turns, Claude should set background: true.

Blocking waits are capped to responsive slices by default. When codex_followup or codex_wait_any returns completed: false, the Codex session is still running; call the wait tool again or read codex://sessions/{session_id}.

When app-server sessions use the Codex desktop binary, they are recorded as normal top-level Codex threads rather than hidden daemon work. The plugin sets the thread name from Claude's task label when the installed Codex app-server supports thread naming. When Claude explicitly cancels a session, or when retention pruning removes an old session, the plugin best-effort archives the matching Codex Desktop thread before closing the app-server child. It does not hard-delete threads, and recoverable sessions are not archived during normal MCP shutdown.

Safety Model

The default execution mode is conservative:

• --sandbox read-only
• approval_policy="never"
• prompt text sent over stdin, not argv
• secret-looking environment variables are not forwarded unless explicitly requested
• large tool responses are compacted before returning to Claude

Full local access is opt-in per call:

{
  "full_access": true
}

Use that only when the user explicitly wants Codex to edit files, write git state, use DNS/network, install packages, or behave like a normal unrestricted Codex run.

Advanced callers can still request advanced.sandbox: "workspace-write" for project-scoped writes, and the patcher role uses that sandbox because its job is to suggest or prepare patches. That is not full access: arbitrary filesystem writes and DNS/network remain disabled unless full_access: true is set.

Documentation

• Usage guide - tools, examples, models, sessions, env vars.
• Architecture - process model, app-server sessions, durability, logging.
• Development - setup, local Claude linking, test tiers, release checklist.
• Troubleshooting - diagnostics, logs, common failure modes.
• Known limitations - sharp edges and operational constraints.
• Release notes - current release highlights and validation.
• Security policy - default sandboxing, logs, reporting.
• Contributing - contribution expectations and local checks.

MCP Tool Families

Use case	Preferred tools
One read-only Codex task	codex_task
Several independent tasks	codex_task_group
Persistent context	codex_task with keep_session: true, then codex_followup
Long-running sessions	codex_task with background: true, then codex_followup
First completed background task	codex_wait_any
Live steering	codex_followup with mode: "steer"
Stop running work	codex_followup with mode: "cancel"
Session progress	MCP resource codex://sessions/{session_id}
Diagnostics	MCP resources codex://status, codex://doctor, codex://usage

Prefer Codex over native Task when the user wants an independent frontier-model second opinion, deep technical review, complex codebase exploration, server or deployment investigation, or adversarial validation. Prefer native Task when the work depends heavily on Claude's conversation history or Claude-only built-in tools.

Legacy tools such as ask_codex, run_agent, run_agents, start_session, and send_session_prompt are hidden by default. Set CODEX_SUBAGENTS_ENABLE_LEGACY_TOOLS=1 only for older clients that still call the pre-refactor names.

Debug tools such as codex_status, codex_doctor, codex_usage_guide, codex_choose_tool, and codex_export_debug_bundle are hidden by default. Set CODEX_SUBAGENTS_ENABLE_DEBUG_TOOLS=1 only when a client needs tool-callable diagnostics instead of the MCP diagnostic resources.

Development

npm install
npm run build
npm run test:ci
npm run validate:plugin

For local install/update:

npm run install:local
npm run update:local

test:ci is portable and uses the fake Codex binary. It does not require live Claude or Codex credentials.

Opt-in live checks are available for hardening:

npm run test:codex-runtime
npm run test:real-matrix
npm run test:claude-orchestration
npm run test:claude-real-codex
npm run test:claude-real-session

See Development for the full test matrix.

Project Status

Current release: v0.3.1.

This project is early, but it is already tested across:

• stdio MCP protocol flows
• fake Codex reliability and stress cases
• Codex desktop runtime probes
• app-server protocol contract checks
• Claude Code plugin validation
• opt-in real Claude Code plus real Codex end-to-end runs

The most important invariant is that routine delegation stays read-only unless the caller explicitly opts into full local access.

License

MIT