Skip to main content
Glama
G0d2i11a

subcodex-mcp

by G0d2i11a
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

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.

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.

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

Available Tools

2 tools
replyC

Continue a Codex conversation by providing the thread id and prompt

ParametersJSON Schema
NameRequiredDescriptionDefault
levelNoExecution level (optional, for log naming): L1=Executor, L2=Builder, L3=Autonomous, L4=Specialist
promptYesThe next user prompt to continue the conversation
threadIdYesThe thread id for this Codex session
maxRecoveryAttemptsNoMax auto-recovery attempts when stalled (default: 2)
stallTimeoutMinutesNoMinutes of inactivity before detecting stall (default: 5)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full responsibility for behavioral disclosure. It only mentions continuing a conversation but does not describe any execution behavior, return format, error conditions, or side effects. This is a significant gap for a tool that likely invokes a long-running process.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no wasted words. It states the action and required inputs efficiently, making it easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having no output schema and 5 parameters, the description is very thin. It doesn't mention what happens after continuing the conversation (e.g., execution, return of results, async behavior), nor does it provide context for when to use this tool. The agent is left with only the bare action and input names, which is insufficient for a tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All 5 parameters have schema descriptions (100% coverage), so the description adds minimal value beyond the schema. It does mention 'thread id' and 'prompt', reinforcing the essential inputs, but it doesn't explain nuanced behaviors like the optional level or recovery settings beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool continues a Codex conversation with a specific verb ('Continue'), resource ('Codex conversation'), and required inputs (thread id and prompt). It is distinct from the sibling 'run' though not explicitly differentiated, so it misses the top score for lacking explicit sibling contrast.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus the sibling 'run' or any other alternative. It simply states what it does without explaining context or prerequisites, leaving the agent without decision support.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

runB

Run a Codex session with streaming progress, stall detection, and auto-recovery

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdNoWorking directory for the session
levelNoExecution level: L1=Executor, L2=Builder, L3=Autonomous, L4=Specialist
modelNoOptional model override (e.g. 'gpt-5.2')
promptYesThe prompt to send to Codex
sandboxModeNoSandbox mode for command execution
approvalPolicyNoApproval policy for commands
maxRecoveryAttemptsNoMax auto-recovery attempts when stalled (default: 2)
stallTimeoutMinutesNoMinutes of inactivity before detecting stall (default: 5)

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It adds some behavioral info (streaming, stall detection, auto-recovery), but omits side effects, permission requirements, and session lifecycle. Given the tool's potential to execute code, this is only minimal disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One concise sentence that front-loads the core purpose and key features. No filler or redundant content, every word provides value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is complex (8 parameters, 3 enums, potentially long-running session) but the description is one line. It fails to explain return values, error handling, or operational considerations. The schema covers parameters but not the overall workflow.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with every parameter documented in the input schema. The tool description adds no parameter-specific meaning, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (Run) and resource (Codex session), and includes distinctive features like streaming progress and stall detection. It implicitly differentiates from the sibling tool 'reply' but does not explicitly contrast them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs. the sibling 'reply' tool, nor any exclusions or prerequisites. The description implies running a session but lacks practical context for agent decision-making.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv1.1.2
    • First observedreply
    • First observedrun
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.3/5.0
Disambiguation5/5

The two tools are clearly distinct: 'run' starts a new Codex session, while 'reply' continues an existing one. The descriptions emphasize different purposes, so there is no ambiguity about which tool to use.

Naming Consistency5/5

Both tools are named with a single lowercase verb ('run' and 'reply'), following a consistent pattern. There is no mixing of naming conventions or unpredictable styles.

Tool Count3/5

With only 2 tools, the server feels thin, especially since it handles session management. However, for the narrow scope of starting and continuing a Codex conversation, the count is reasonable but borderline.

Completeness3/5

The core workflow of starting and continuing a session is covered, but there are notable gaps such as listing existing sessions, canceling a run, or retrieving status. This prevents full lifecycle coverage.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/G0d2i11a/subcodex-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server