subcodex-mcp

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:

| Role | Claude Code | Codex | |------|-------------|-------| | Analogy | Product Manager who understands requirements | Technical expert in deep focus | | Strengths | Planning, communication, context understanding | Coding, debugging, implementation | | Best at | Breaking down tasks, writing specs, verification | Writing code, fixing bugs, refactoring |

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.

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.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | prompt | string | Yes | The prompt to send to Codex | | cwd | string | No | Working directory for the session | | model | string | No | Model override (e.g., 'gpt-5.2') | | sandboxMode | string | No | read-only, workspace-write, or danger-full-access | | approvalPolicy | string | No | never, on-request, on-failure, or untrusted | | level | string | No | Execution level: L1, L2, L3, L4 (for log naming) | | stallTimeoutMinutes | number | No | Minutes of inactivity before detecting stall (default: 5) | | maxRecoveryAttempts | number | No | Max auto-recovery attempts when stalled (default: 2) |

reply

Continue an existing Codex conversation.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | threadId | string | Yes | The thread ID from a previous session | | prompt | string | Yes | The next prompt to continue the conversation | | level | string | No | Execution level for log naming | | stallTimeoutMinutes | number | No | Minutes of inactivity before detecting stall (default: 5) | | maxRecoveryAttempts | number | No | Max auto-recovery attempts when stalled (default: 2) |

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