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

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

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