claudex

claudex

🌐 English · 한국어

Use OpenAI Codex (GPT-5.x) as a balanced sub-agent under Claude Code.

Claude is the supervisor and final decision-maker; Codex does the token-heavy grunt work (exploration, first drafts, second-opinion reviews) inside its own context, so that work runs on your OpenAI/ChatGPT quota instead of Anthropic tokens. Claude reviews Codex's output before anything is applied — quality is protected by review, and with two independent frontier models cross-checking, it often improves.

This repo is a Claude Code plugin marketplace with one plugin: claudex.

What the plugin sets up

• codex MCP server — auto-registered via the bundled .mcp.json (runs codex mcp-server).
• codex skill — the balanced-delegation workflow + safety rules (loaded on demand, costs no context until used).
• /claudex:delegate <task> — delegate one focused task to Codex, then review.
• /claudex:cross-review <target> — bounded Claude↔Codex feedback loop with a user-chosen round count.
• /claudex:mode — choose how work is split between Claude and Codex (solo | balanced | codex | max).
• /claudex:status — show the current work-split mode and Codex status (login, version, model, MCP link).
• SessionStart hook — injects a short standing policy each session so Claude defaults to the balanced posture (always-on).

Prerequisites

1. Claude Code installed.
2. Codex CLI installed and logged in, in the same environment as Claude Code (if Claude runs in a container, Codex must be installed and logged in inside that container):

   curl -fsSL https://chatgpt.com/codex/install.sh | sh   # install
   codex login                                            # or: codex login --device-auth
   codex login status                                     # verify
   

3. Pick Codex's model/effort in ~/.codex/config.toml (the MCP server inherits these):

   model = "gpt-5.5"
   model_reasoning_effort = "xhigh"
   

Install

# 1) Add this repo as a marketplace (GitHub repo, URL, or local path all work)
claude plugin marketplace add security-engineer/claudex

# 2) Install the plugin
claude plugin install claudex@claudex

# 3) Restart Claude Code so the MCP server, hook, skill, and commands load

Local development install (no GitHub needed):

claude plugin marketplace add /absolute/path/to/claudex
claude plugin install claudex@claudex

Verify:

claude plugin list
claude mcp list          # codex should be ✔ Connected
# in a session:  /mcp   then   /claudex:delegate hello   then   /claudex:cross-review <target>

---

Usage

Division of labor

• Claude (Opus 4.8) = supervisor — final judgment, applying edits, running tests, reconciling.
• Codex (GPT-5.x, xhigh) = sub-agent — token-heavy exploration, first drafts, independent review, edge-case hunting. Runs on your OpenAI/ChatGPT quota, not Anthropic tokens.

The SessionStart policy nudges Claude to delegate, but delegation is not automatic — you control the split with /claudex:mode (set codex/max to push most work to Codex), and Codex earns its keep on token-heavy code work (exploration, first drafts, reviews) rather than small edits or harness/config tasks. Drive it directly with the commands below.

/claudex:delegate <task>

Delegate a single focused task to Codex, then review the result before applying.

Flow: scope files → delegate (MCP or codex exec) → review critically → you (Claude) apply + test.

Examples

• /claudex:delegate review the diff in src/auth/ and list edge cases
• /claudex:delegate draft a refactor of utils/date.py to remove duplication
• /claudex:delegate find the root cause of the failing test in tests/test_api.py

Codex runs read-only by default; it writes only when a patch is explicitly required. Never include secrets or huge dataset dirs in scope.

/claudex:cross-review <target> [rounds=N] [style=ab|independent|debate]

Run a bounded Claude↔Codex feedback loop, then Claude delivers a verdict.

Arguments

• target — a file, a diff (e.g. “the staged diff”), or a question/topic. Everything that isn't a key=value flag.
• rounds=N — you choose how many critique↔rebuttal rounds. Default 2. Hard ceiling 5 (clamped — it never loops past 5, even if you ask for more).
• style — ab (default: one drafts, the other critiques), independent (both solve separately, Claude diffs them), or debate (adversarial back-and-forth).