subcodex

MCP server for Claude Code to use OpenAI Codex as a subagent, with stall detection and auto-recovery.

中文文档

Why subcodex?

Claude Code and Codex have complementary strengths:

subcodex bridges these two, letting Claude Code orchestrate Codex as a subagent:

• Claude Code handles the "what" and "why" (requirements, planning, verification)

• Codex handles the "how" (implementation, debugging)

This combination delivers better results than either tool alone.

Related MCP server: codex-bridge

Features

• Run Codex sessions with streaming progress

• Automatic stall detection (configurable timeout)

• Auto-recovery attempts when stalled

• Progress logging to ~/.claude/codex-logs/

• Thread continuation support via codex-reply

Usage Modes

Configure in your CLAUDE.md to control when subcodex is used:

Mode 1: Full Subagent

All code modifications go through subcodex. Claude only does analysis, planning, and verification.

## Subagent Mode: full-subagent

All code changes must go through `mcp__subcodex__run`:
- Claude: analyze, plan, write Codex Contract, verify results
- Subcodex: all file edits, code generation, refactoring

Mode 2: Directory-Based

Different directories are handled by different executors.

## Subagent Mode: directory-based

| Scope | Executor |
|-------|----------|
| `apps/web/**/*` | Claude direct |
| `apps/api/**/*`, `packages/**/*` | subcodex |
| docs, config | Claude direct |

Mode 3: Fallback

Claude handles everything, but falls back to subcodex on failure.

## Subagent Mode: fallback

- Claude attempts all code changes directly
- After 2 failed attempts → automatically use subcodex
- Windows file lock errors → immediately use subcodex

Installation

From npm

npx subcodex-mcp

From source

git clone https://github.com/G0d2i11a/subcodex.git
cd subcodex
pnpm install
pnpm build

Configuration

Add to your Claude Code MCP config (~/.claude.json):

{
  "mcpServers": {
    "subcodex": {
      "command": "npx",
      "args": ["-y", "subcodex-mcp"],
      "env": {},
      "type": "stdio"
    }
  }
}

Or for local development:

{
  "mcpServers": {
    "subcodex": {
      "command": "node",
      "args": ["/path/to/subcodex/dist/index.js"],
      "env": {},
      "type": "stdio"
    }
  }
}

Tools

run

Start a new Codex session.

reply

Continue an existing Codex conversation.

Stall Detection

The server monitors Codex sessions for activity. If no events are received within the timeout period:

1. Marks the session as stalled

2. Attempts auto-recovery by sending a recovery prompt

3. Retries up to maxRecoveryAttempts times

4. Returns TIMEOUT status with needsUserInput: true if all recovery attempts fail

Handling needsUserInput

When the response contains needsUserInput: true, Claude should use AskUserQuestion to ask the user how to proceed. Add this rule to your CLAUDE.md:

## Subcodex Stall Handling

When `mcp__subcodex__run` returns `needsUserInput: true`:
- Use AskUserQuestion to ask the user how to proceed
- Options: retry, skip current task, manual intervention

Response Format

{
  "threadId": "abc123...",
  "level": "L2",
  "content": "Final response from Codex",
  "progressLog": "~/.claude/codex-logs/progress-L2-xxx-PASS.log",
  "stats": {
    "totalItems": 10,
    "commands": 3,
    "fileChanges": 2,
    "mcpCalls": 0,
    "usage": {
      "input_tokens": 1000,
      "output_tokens": 500
    }
  },
  "filesModified": ["create: src/foo.ts", "modify: src/bar.ts"],
  "recovery": {
    "attempted": false
  },
  "needsUserInput": false
}

When stalled and recovery fails:

{
  "threadId": "abc123...",
  "level": "L2",
  "content": "",
  "progressLog": "~/.claude/codex-logs/progress-L2-xxx-TIMEOUT.log",
  "recovery": {
    "attempted": true,
    "attempts": 2,
    "recovered": false,
    "lastError": "Still stalled after recovery attempt"
  },
  "needsUserInput": true
}

Result Levels

Log files are renamed with result level suffix:

• PASS - Success (log file deleted)

• FAIL - Command or file change failed

• ERROR - Exception occurred

• TIMEOUT - Stalled and recovery failed

Requirements

• Node.js 18+

• OpenAI Codex SDK credentials configured

License

MIT