Claude Code Codex Subagents

CI License: MIT Node >=20

Claude Code plugin for OpenAI Codex subagents. Run Codex, Codex Spark, 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.
• Codex Spark support: Claude can request quick focused Spark checks without remembering model slugs.
• 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.
• Codex Spark side checks for fast focused technical passes.
• Read-only-by-default delegation with explicit opt-in for full local Codex capabilities.

Quick Start

Requirements:

• Node.js 20 or newer
• Claude Code
• Codex CLI, preferably the Codex desktop app

Install the plugin once:

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

Restart Claude Code, then ask Claude in any project:

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

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.

Use Spark

Use Codex Spark to do a fast focused pass on the tool descriptions.

Claude can pass advanced.model: "spark" instead of remembering the exact Spark model slug.

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.0.

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