Codex MCP Bridge Lite

A local stdio MCP server that exposes two tools for Claude CLI and executes codex exec non-interactively.

• consult_codex
• consult_codex_with_stdin

Placeholder convention used in this README:

• <project-root> = your local clone path for this repository (for example, ~/workspace/codex-mcp-bridge).

Features

• Uses codex exec - (prompt via stdin) in non-interactive mode.
• Captures final output via --output-last-message file first.
• Default sandbox is read-only.
• Optional directory allowlist via CODEX_ALLOWED_DIRS.
• Output truncation via CODEX_MAX_OUTPUT_CHARS.
• Concise error handling for missing CLI/auth/timeout/non-zero exits.
• Keeps MCP stdout clean (no debug logging to stdout).

Requirements

• Python 3.10+
• Codex CLI installed and authenticated (codex login)

Install

From PyPI (recommended)

pip install codex-mcp-bridge

Or with uv:

uv pip install codex-mcp-bridge

From source (development)

cd <project-root>
uv venv
source .venv/bin/activate
uv pip install -e .[dev]

Run (stdio MCP)

After installing from PyPI:

codex-mcp-bridge

Or from source:

cd <project-root>
uv run codex-mcp-bridge

Claude CLI registration

After pip install (recommended)

claude mcp add codex-bridge -- codex-mcp-bridge

From source

claude mcp add codex-bridge -- uv --directory <project-root> run codex-mcp-bridge

Verify registration

claude mcp get codex-bridge

Sub-Agent Skills

Example skills are provided in two formats:

• Skills (examples/claude-skills/) — proper .claude/skills/ format with YAML frontmatter. Supports context: fork (isolated subagent), allowed-tools restrictions, and progressive disclosure. Recommended.
• Custom Commands (examples/claude-commands/) — legacy .claude/commands/ format. Simpler but lacks skill features like forking and tool restrictions.

Available Skills

Full sub-agent mode

Skill	Description	Sandbox
codex-subagent	Comprehensive orchestrator — auto-selects tool, sandbox, and format based on task. Supports multi-step delegation. Runs in forked context.	auto

Read-only (analysis, no file changes)

Skill	Description	Sandbox
codex-review	Code review — bugs, security, performance	read-only
codex-test	Generate tests for specified code	read-only
codex-explain	Explain code logic and design decisions	read-only
codex-ask	General technical question to Codex	read-only

Write-enabled (can modify/create files)

Skill	Description	Sandbox
codex-fix	Fix bugs and issues in code	workspace-write
codex-refactor	Refactor code for readability and structure	workspace-write
codex-generate	Generate new code/files from description	workspace-write

Install Skills (Recommended)

Copy skill directories to your project's .claude/skills/:

# From cloned repo
cp -r <project-root>/examples/claude-skills/* .claude/skills/

# Or download a single skill from GitHub
mkdir -p .claude/skills/codex-subagent
curl -sL "https://raw.githubusercontent.com/dante01yoon/codex-mcp-bridge/main/examples/claude-skills/codex-subagent/SKILL.md" \
  -o ".claude/skills/codex-subagent/SKILL.md"

Each skill is a directory with a SKILL.md file:

.claude/skills/
├── codex-subagent/
│   └── SKILL.md          # Full orchestrator with fork context
├── codex-review/
│   └── SKILL.md          # Code review (read-only)
├── codex-fix/
│   └── SKILL.md          # Bug fix (workspace-write)
├── codex-generate/
│   └── SKILL.md          # Code generation (workspace-write)
├── codex-test/
│   └── SKILL.md          # Test generation (read-only)
├── codex-explain/
│   └── SKILL.md          # Code explanation (read-only)
├── codex-ask/
│   └── SKILL.md          # Question delegation (read-only)
└── codex-refactor/
    └── SKILL.md          # Refactoring (workspace-write)

SKILL.md Format

Each skill uses YAML frontmatter for metadata:

---
name: Codex Sub-Agent
description: Orchestrates task delegation to Codex via MCP bridge.
user-invocable: true
allowed-tools:
  - mcp__codex-bridge__consult_codex
  - mcp__codex-bridge__consult_codex_with_stdin
  - Read
  - Glob
  - Grep
context: fork
argument-hint: Describe the task to delegate to Codex
---

(Skill instructions here...)

Key frontmatter fields:

• user-invocable: true — enables /skill-name slash command
• allowed-tools — restricts which tools the skill can use
• context: fork — runs skill in an isolated subagent (prevents context pollution)
• argument-hint — hint text shown when user types the slash command

Install Custom Commands (Legacy)

If you prefer the simpler legacy format:

mkdir -p .claude/commands
cp <project-root>/examples/claude-commands/*.md .claude/commands/

Basic Usage

/codex-subagent Review src/config.py, fix any issues, then generate tests
/codex-review src/server.py
/codex-test src/runner.py
/codex-explain src/config.py
/codex-ask "How does MCP stdio transport work?"
/codex-fix src/runner.py "timeout is not applied when value is 0"
/codex-refactor src/config.py
/codex-generate "Create a health check endpoint that returns server status and uptime"

Workflow Examples

Workflow 1: Review → Fix

/codex-review src/runner.py
  → "3 issues found: [critical] timeout not handled when value is 0..."

/codex-fix src/runner.py "subprocess timeout not handled when value is 0"
  → Codex fixes the issue and applies changes

Workflow 2: Generate → Test → Review

/codex-generate "Add a validate_schema function that checks tool input against JSON Schema"
  → Codex generates src/codex_bridge_mcp/validator.py

/codex-test src/codex_bridge_mcp/validator.py
  → Codex generates tests/test_validator.py

/codex-review src/codex_bridge_mcp/validator.py
  → Codex reviews the generated code for improvements

Workflow 3: Explain → Refactor

/codex-explain src/codex_bridge_mcp/config.py
  → "Settings class loads config with precedence: tool > env > file > defaults..."

/codex-refactor src/codex_bridge_mcp/config.py
  → Codex refactors with understanding of the design intent preserved

Workflow 4: Multi-Step via Sub-Agent

/codex-subagent Analyze the error handling in runner.py, plan improvements, implement them, then verify
  → Step 1: Codex analyzes (read-only)
  → Step 2: Codex plans improvements (read-only)
  → Step 3: Codex applies changes (workspace-write)
  → Step 4: Codex verifies result (read-only)

Auto-delegation via CLAUDE.md

To make Claude automatically prefer Codex for coding tasks (without explicit slash commands), add the provided snippet to your project's CLAUDE.md:

cat <project-root>/examples/CLAUDE.md.example >> CLAUDE.md

This makes Claude delegate code review, test generation, and technical questions to Codex by default. See examples/CLAUDE.md.example for the full configuration.

Default Launcher Command (Recommended)

Use this launcher to make Claude prefer codex-bridge automatically for coding tasks, without writing explicit templates each time.

Launcher script:

• <project-root>/scripts/claude_codex_launcher.sh

Run:

<project-root>/scripts/claude_codex_launcher.sh

Optional shell alias:

alias claude-codex='<project-root>/scripts/claude_codex_launcher.sh'

Then use:

claude-codex

Audit launcher (verifies whether Codex bridge tools were actually used):

<project-root>/scripts/claude_codex_audit.sh "Return exactly BRIDGE_OK"

Optional audit alias:

alias claude-codex-audit='<project-root>/scripts/claude_codex_audit.sh'

The audit launcher prints:

• === Claude Result === final answer text
• tools_used: all MCP/tool calls observed
• codex_bridge_used: yes/no explicit Codex usage signal
• codex_bridge_tools: exact codex-bridge tool names used

Why this launcher is useful:

• Consistent behavior: always injects Codex-first guidance via --append-system-prompt.
• Less friction: you do not need to paste tool-call templates for every technical query.
• Fewer permission denials: pre-sets --allowedTools for both bridge tools.
• Safer defaults: guidance includes sandbox=read-only and timeout=180 as baseline.

Customizing launcher behavior:

export CLAUDE_CODEX_APPEND_PROMPT='Your custom codex-first instruction'
export CLAUDE_CODEX_ALLOWED_TOOLS='mcp__codex-bridge__consult_codex,mcp__codex-bridge__consult_codex_with_stdin'

Korean quick note:

• 이 런처는 Claude 기본 시스템 프롬프트를 제거하지 않고, Codex 우선 지침을 추가(append)합니다.
• 따라서 기본 동작은 유지하면서 Codex 도구 호출 확률을 높이는 방식입니다.

Quick Guide (EN)

1. Install and run:

pip install codex-mcp-bridge
codex-mcp-bridge

Or from source:

cd <project-root>
uv venv && source .venv/bin/activate
uv pip install -e .[dev]
uv run codex-mcp-bridge

2. Register MCP server in Claude CLI:

# After pip install
claude mcp add codex-bridge -- codex-mcp-bridge

# Or from source
claude mcp add codex-bridge -- uv --directory <project-root> run codex-mcp-bridge

3. Verify MCP connection:

claude mcp get codex-bridge

4. Verify end-to-end tool calls through Claude:

cd ~
claude -p --output-format text --permission-mode dontAsk --allowedTools mcp__codex-bridge__consult_codex -- "Call mcp__codex-bridge__consult_codex with arguments {\"query\":\"Return exactly BRIDGE_OK\",\"directory\":\"<project-root>\",\"format\":\"text\",\"timeout\":180,\"sandbox\":\"read-only\"}. Return only the tool result."

cd ~
claude -p --output-format text --permission-mode dontAsk --allowedTools mcp__codex-bridge__consult_codex_with_stdin -- "Call mcp__codex-bridge__consult_codex_with_stdin with arguments {\"stdin_content\":\"ping\",\"prompt\":\"Return exactly PONG\",\"directory\":\"<project-root>\",\"format\":\"text\",\"timeout\":180,\"sandbox\":\"read-only\"}. Return only the tool result."

5. Troubleshooting:

• tool denied due to permission restrictions: add --allowedTools mcp__codex-bridge__consult_codex or use a permission mode that allows MCP tools.
• Codex timed out after 90 seconds: increase tool timeout (e.g. 180) and keep prompts short/explicit.
• codex CLI not found: install Codex CLI and check PATH.
• Codex authentication appears unavailable: run codex login.

빠른 가이드 (KR)

1. 설치 및 실행:

pip install codex-mcp-bridge
codex-mcp-bridge

또는 소스에서:

cd <project-root>
uv venv && source .venv/bin/activate
uv pip install -e .[dev]
uv run codex-mcp-bridge

2. Claude CLI에 MCP 서버 등록:

# pip 설치 후
claude mcp add codex-bridge -- codex-mcp-bridge

# 또는 소스에서
claude mcp add codex-bridge -- uv --directory <project-root> run codex-mcp-bridge

3. MCP 연결 상태 확인:

claude mcp get codex-bridge

4. Claude 경유 E2E 도구 호출 검증:

cd ~
claude -p --output-format text --permission-mode dontAsk --allowedTools mcp__codex-bridge__consult_codex -- "Call mcp__codex-bridge__consult_codex with arguments {\"query\":\"Return exactly BRIDGE_OK\",\"directory\":\"<project-root>\",\"format\":\"text\",\"timeout\":180,\"sandbox\":\"read-only\"}. Return only the tool result."

cd ~
claude -p --output-format text --permission-mode dontAsk --allowedTools mcp__codex-bridge__consult_codex_with_stdin -- "Call mcp__codex-bridge__consult_codex_with_stdin with arguments {\"stdin_content\":\"ping\",\"prompt\":\"Return exactly PONG\",\"directory\":\"<project-root>\",\"format\":\"text\",\"timeout\":180,\"sandbox\":\"read-only\"}. Return only the tool result."

5. 문제 해결:

• permission restrictions로 도구가 거부되면 --allowedTools에 해당 MCP 도구를 명시하거나 MCP 허용 모드로 실행합니다.
• Codex timed out after 90 seconds가 발생하면 도구 인자의 timeout을 늘리고 요청을 짧고 명확하게 작성합니다.
• codex CLI not found 오류는 Codex CLI 설치 또는 PATH 설정 문제입니다.
• 인증 오류가 보이면 codex login을 먼저 수행합니다.

Claude Prompt Templates (EN/KR)

Use these templates when you want Claude to invoke Codex via MCP first.

Template A: Codex-first simple text result (EN)

Call mcp__codex-bridge__consult_codex with arguments {"query":"<YOUR_TASK>","directory":"<project-root>","format":"text","timeout":180,"sandbox":"read-only"}.
Return only the tool result.

Example:

Call mcp__codex-bridge__consult_codex with arguments {"query":"Return exactly BRIDGE_OK","directory":"<project-root>","format":"text","timeout":180,"sandbox":"read-only"}.
Return only the tool result.

템플릿 A: Codex 우선 단순 텍스트 결과 (KR)

mcp__codex-bridge__consult_codex 도구를 다음 인자로 호출해줘: {"query":"<작업 지시문>","directory":"<project-root>","format":"text","timeout":180,"sandbox":"read-only"}.
그리고 도구 결과만 그대로 반환해줘.

예시:

mcp__codex-bridge__consult_codex 도구를 다음 인자로 호출해줘: {"query":"정확히 BRIDGE_OK만 반환해","directory":"<project-root>","format":"text","timeout":180,"sandbox":"read-only"}.
그리고 도구 결과만 그대로 반환해줘.

Template B: Structured JSON result (EN)

Call mcp__codex-bridge__consult_codex with arguments {"query":"<YOUR_TASK: return strict JSON>","directory":"<project-root>","format":"json","timeout":180,"sandbox":"read-only"}.
Return only the tool result without markdown fences.

템플릿 B: 구조화된 JSON 결과 (KR)

mcp__codex-bridge__consult_codex 도구를 다음 인자로 호출해줘: {"query":"<JSON으로 응답해야 하는 작업>","directory":"<project-root>","format":"json","timeout":180,"sandbox":"read-only"}.
마크다운 코드블록 없이 도구 결과만 반환해줘.

Template C: Large input via stdin block (EN)

Call mcp__codex-bridge__consult_codex_with_stdin with arguments {"stdin_content":"<LARGE_INPUT>","prompt":"<TASK_PROMPT>","directory":"<project-root>","format":"json","timeout":180,"sandbox":"read-only"}.
Return only the tool result.

템플릿 C: 큰 입력 전달 (KR)

mcp__codex-bridge__consult_codex_with_stdin 도구를 다음 인자로 호출해줘: {"stdin_content":"<큰 입력 데이터>","prompt":"<작업 지시문>","directory":"<project-root>","format":"json","timeout":180,"sandbox":"read-only"}.
그리고 도구 결과만 반환해줘.

CLI tip (when using claude -p):

• If MCP tool calls are denied, include --allowedTools mcp__codex-bridge__consult_codex (or _with_stdin).
• If timeout occurs, increase timeout in tool arguments (e.g. 180 or 240).

How It Works (Claude -> Codex CLI Bridge)

sequenceDiagram
    participant U as "User"
    participant C as "Claude CLI"
    participant M as "MCP Server (codex-bridge)"
    participant X as "Codex CLI (codex exec)"
    participant F as "Output File (--output-last-message)"

    U->>C: "요청 입력"
    C->>M: "MCP tool call (consult_codex / consult_codex_with_stdin)"
    M->>M: "입력 검증 (Pydantic), 디렉터리/allowlist 검사"
    M->>X: "subprocess.run(codex exec - ... --sandbox ...)"
    X->>F: "최종 답변 기록"
    X-->>M: "exit code + stdout/stderr"
    M->>M: "output 파일 우선 읽기, 실패 시 stdout fallback"
    M->>M: "출력 길이 제한/오류 표준화"
    M-->>C: "단일 문자열 결과 반환"
    C-->>U: "최종 응답"

핵심 동작 원리:

• Claude는 오케스트레이터 역할만 하고, 코드 생성/분석 실행은 MCP 도구를 통해 Codex CLI에 위임합니다.
• 브리지는 codex exec를 비대화식으로 실행하며, stdout 오염을 막기 위해 프로토콜 통신은 stdout, 디버그/오류는 stderr로 분리합니다.
• Codex 결과는 --output-last-message 파일에서 우선 읽고, 파일 읽기 실패 시 캡처된 stdout으로 대체합니다.
• 보안/안정성은 기본 read-only sandbox, 디렉터리 allowlist, timeout, stderr 절단, output truncation으로 보장합니다.

About temporary output file (--output-last-message)

• 브리지는 요청마다 OS 임시 디렉터리에 1회성 파일을 생성합니다.
• Codex의 마지막 답변을 그 파일에서 먼저 읽습니다.
• 처리 후에는 파일을 삭제합니다 (output_file.unlink(missing_ok=True) in src/codex_bridge_mcp/runner.py).
• 즉, 정상 흐름에서는 파일이 남지 않습니다.

Why file-first is useful (real examples)

현재 버전에서는 보통 최종 답변이 stdout에 깔끔히 나오지만, 운영 환경에서는 아래와 같은 변화가 생길 수 있습니다.

1. CLI 옵션/모드 변경으로 stdout 포맷이 달라지는 경우 : 예를 들어 --json 같은 이벤트 출력 모드가 활성화되면 stdout이 JSONL 이벤트 스트림이 될 수 있습니다. 이때 문자열 파싱 기반 브리지는 쉽게 깨질 수 있습니다.

2. 향후 Codex CLI 릴리즈에서 stdout에 상태 메시지가 추가되는 경우 : 배너/진행상태/요약 정보가 stdout으로 섞이면 "최종 답변만 반환" 계약이 깨질 수 있습니다.

3. 실행 래퍼/셸 훅이 stdout에 텍스트를 주입하는 경우 : 내부 정책상 표준출력에 prefix/suffix를 붙이는 wrapper를 쓰는 환경에서는 출력 오염 가능성이 있습니다.

파일 우선 전략은 이런 변화와 무관하게 "최종 답변 소스"를 고정해 주기 때문에, 브리지의 안정성과 파싱 신뢰성을 높입니다.

Configuration

Settings can be configured via a JSON file, environment variables, or both.

Precedence: tool input > environment variable > config file > default.

JSON config file

Place codex-bridge.json (or .codex-bridge.json) in your project root or ~/.config/codex-bridge/:

{
  "default_timeout": 180,
  "default_sandbox": "read-only",
  "default_model": null,
  "allowed_dirs": [],
  "max_output_chars": 12000
}

An example is provided in examples/codex-bridge.json.

Environment variables

Environment variables override JSON config values:

• CODEX_DEFAULT_MODEL (optional)
• CODEX_DEFAULT_TIMEOUT (default: 90)
• CODEX_DEFAULT_SANDBOX (default: read-only)
• CODEX_ALLOWED_DIRS (optional CSV absolute/relative dirs)
• CODEX_MAX_OUTPUT_CHARS (default: 12000)

Environment variables can also be set at MCP registration time:

claude mcp add -e CODEX_DEFAULT_TIMEOUT=180 codex-bridge -- codex-mcp-bridge

Tool Inputs

consult_codex

• query (required)
• directory (default .)
• format (text | json | code, default from server json)
• timeout (seconds, optional)
• model (optional)
• sandbox (read-only | workspace-write | danger-full-access, optional)

consult_codex_with_stdin

• stdin_content (required)
• prompt (required)
• plus all options from consult_codex

Test

cd <project-root>
uv run pytest

Smoke / Regression Scripts

cd <project-root>
./scripts/check_stdout_clean.sh

cd <project-root>
./scripts/it_smoke_codex_bridge.sh