Languages: English · 简体中文
Turn Claude Code into a multi-agent coding system powered by OpenAI Codex. A zero-install Claude Code plugin for multi-agent orchestration — delegate implementation, code reviews, and planning to a pool of parallel Codex workers, each running in its own isolated git worktree, via the MCP (Model Context Protocol) standard.
The bridge between Claude Code and the OpenAI Codex ecosystem: Claude stays in orchestrator mode (planning, synthesis, interactive work), Codex workers absorb the grunt work. Get dual-model PR review, resumable sessions across conversations, and role-based agent specialization — while preserving your Claude quota for what Claude does best.
- ⚡ Parallel execution. Fan out N Codex workers on independent subtasks in N isolated worktrees. Finish work that would serialize in a single Claude session.
- 🛡️ Isolated experimentation. Every implementer runs in its own
git worktreeon its own branch. Try three approaches in parallel; keep the best; discard the rest. Zero risk to your main tree. - 🔀 Two model families beat one. Launch a Codex (GPT) reviewer alongside your Claude review — different models catch different classes of bugs. The plugin materializes PRs in detached worktrees so the reviewer reads real files, not a diff blob.
- 💰 Quota arbitrage. Claude budget running low? Dial delegation up to
maxand route everything Codex can handle over there — Claude stays in orchestrator mode. One knob (minimal/balance/max) controls the split. - 🎯 Role-tuned, observable delegation. Not a thin "forward the prompt" wrapper — a full orchestration layer with role-based specialization (implementer / reviewer / planner / generic), resumable sessions, per-role sandbox + timeout, and first-class session tracking in a persisted registry.
- 🧰 Production engineering. 62 unit tests, strict TypeScript, CI on Node 20/22. Designed from an actual spike of Codex's MCP protocol — no stdout parsing, no brittle scraping. Git worktrees for parallelism, MCP protocol for transport, TOML for configuration, sandboxed execution for safety.
| Official OpenAI Codex plugin | magic-cc-codex-worker | |
|---|---|---|
| Single Codex session in Claude Code | ✅ | ✅ |
| Multi-agent orchestration | ❌ | ✅ |
| Parallel worker execution | ❌ | ✅ |
| Git worktree isolation per worker | ❌ | ✅ |
| Role-based specialization | ❌ | ✅ |
| Resumable session continuity | ❌ | ✅ |
| Dual-model PR review | ❌ | ✅ |
| Epic / batch fan-out | ❌ | ✅ |
OpenAI's official Codex plugin lets you use Codex. This plugin lets you scale Codex into a multi-agent coding system inside Claude Code.
Claude Code plugin distribution is a two-step pattern — same as brew tap + brew install or apt-add-repository + apt install. First you register a marketplace (a catalog that lists plugins), then you install one of its plugins. Our marketplace happens to contain only this one plugin, so the names look duplicated — that's normal.
Tells Claude Code "this GitHub repo publishes a plugin catalog." It clones the repo's .claude-plugin/marketplace.json and lists the plugins available from it. No plugin is installed yet.
/plugin marketplace add wenqingyu/magic-cc-codex-worker
Picks one plugin out of the catalog and attaches it to your Claude Code session. The <plugin-name>@<marketplace-name> format disambiguates when a plugin name exists in multiple catalogs.
/plugin install magic-codex@magic-codex
Activates the newly-installed plugin in the current session without a full restart.
/reload-plugins
After reload, run /magic-codex:status to verify — should return an empty agent list, and the 9 magic-codex MCP tools should be registered. If commands don't show up in autocomplete, fully restart Claude Code.
That's it: no clone, no build, no config on your side. Claude Code fetches the repo, reads .claude-plugin/marketplace.json, and installs the plugin with its prebuilt dist/, commands, and agents.
Only the codex CLI itself needs to be installed and authenticated:
codex --version # any 0.122.0+ works
codex login # if not already logged inNode / git / npm are only required if you want to develop the plugin — see Development below.
/magic-codex:spawn implementer "Add rate limiting to /api/upload"
# → returns agent_id, e.g. codex-impl-ab12cd
/magic-codex:status # see all agents
/magic-codex:status codex-impl-ab12cd # single agent
/magic-codex:merge codex-impl-ab12cd # merge the worktree back when done
That's the whole loop: spawn → poll → merge.
- Parallel task execution — spawn N Codex workers that all run at once, each in its own sandboxed branch.
- Isolated experimentation — try multiple approaches to the same task;
/magic-codex:mergethe winner,/magic-codex:discardthe rest. Your main tree is never at risk. - Best-result selection — review each worker's diff independently before anything lands.
- Resumable sessions — worker finished but you need a follow-up?
/magic-codex:resume <agent_id>continues the same Codex thread. - Dual-model review — spawn a Codex reviewer on a PR; read its report alongside your own Claude review.
- Multi-agent workflows — fan out a Linear epic to one worker per child issue; collect results as a batch.
The plugin bundles two MCP servers:
codex mcp-server(from Codex itself) — exposed as-is for the sub-60s synchronous fast path.magic-codex(this project) — async orchestration: spawn in background, track state, manage git worktrees, enforce timeouts, route results back.
Every implementer-role worker runs in its own git worktree so parallel workers never clobber each other's edits. Reviewer-role workers run read-only, optionally inside a detached worktree at a PR's head SHA.
| Tool | Purpose |
|---|---|
spawn |
Launch a Codex agent in the background. Returns agent_id. |
status |
One agent or all — returns current state + output preview. |
result |
Full output of a terminal-state agent. |
resume |
Continue a terminal agent via Codex codex-reply on stored thread_id. |
cancel |
Kill a running agent; marks cancelled. force also removes worktree. |
merge |
Merge a completed implementer's worktree back (squash / ff / rebase). |
discard |
Remove a terminal agent's worktree + branch. |
list |
Filter agents by role / status / issue_id / has_pr / stale age. |
get_delegation_policy |
Read the configured delegation level + guidance. |
Plus the raw codex / codex-reply tools from codex mcp-server.
| Command | Purpose |
|---|---|
/magic-codex:spawn <role> <prompt> |
Launch an agent. |
/magic-codex:status [agent_id] |
Compact progress table. |
/magic-codex:resume <agent_id> <prompt> |
Continue a terminal agent. |
/magic-codex:cancel <agent_id> [--force] |
Kill + optional cleanup. |
/magic-codex:merge <agent_id> |
Merge back. |
/magic-codex:discard <agent_id> |
Remove worktree + branch. |
/magic-codex:review-pr <pr_number> |
Dual-model code review for a PR. |
/magic-codex:fan-out <EPIC-NNN> |
Parallel implementer-per-child for an epic. |
/magic-codex:mode [minimal|balance|max] |
View/set delegation level. |
For Agent({ subagent_type: "...", ... }) dispatch:
implementer— autonomous worktree work + diff reviewreviewer— read-only dual-model reviewplanner— plan-only output for comparison
How aggressively should Claude delegate to Codex?
| Level | Intent |
|---|---|
minimal |
Codex only for things Codex does notably better (second-opinion GPT review, very long runs). |
balance (default) |
Balanced split. Claude handles quick/interactive work; Codex handles big/parallelizable chunks. |
max |
Codex handles everything it can; Claude stays in orchestrator mode. |
Set via (precedence: env > project > user > default):
# Env
export MAGIC_CODEX_DELEGATION_LEVEL=max# magic-codex.toml (project root, committed)
[delegation]
level = "balance"Claude reads the policy via get_delegation_policy at session start.
Built-in presets (src/roles/defaults/):
| Role | Sandbox | Worktree | Timeout |
|---|---|---|---|
implementer |
danger-full-access |
branch-per-agent | 30 min |
reviewer |
read-only |
detached at PR head (when pr_number given) |
10 min |
planner |
read-only |
none | 15 min |
generic |
read-only |
none | 15 min |
Implementer's
danger-full-accessdefault landed in 0.4.0.workspace-writeempirically dropped.git/worktrees/<id>/index.lockwrites for ~33-67% of macOS spawns even with the writable_roots workaround. The agent is already isolated to a throwaway worktree branch, sodanger-full-accessis the smaller blast radius. Override via[roles.implementer] sandbox = "workspace-write"if you need stricter network egress isolation; the lock denials will still happen but 0.4.1's silent-failure detection surfaces them asfailed/kind=sandbox_deniedinstead of a misleadingcompleted.
The per-role model split that was useful in 2025 collapsed in 2026. gpt-5.5 (with gpt-5.4 as a fallback during rollout) is now the unified top model for implementation, review, and planning. The dial that matters is reasoning effort, configured via codex CLI profiles — not via magic-codex.
Recommended approach: leave model unset on every role in magic-codex.toml and let codex inherit your ~/.codex/config.toml defaults + profiles.
A solid codex baseline:
# ~/.codex/config.toml
model = "gpt-5.5"
model_reasoning_effort = "high"
service_tier = "fast"
review_model = "gpt-5.5"
[profiles.coding] # daily work
model_reasoning_effort = "high"
[profiles.deep] # hard reviews / planning / refactors
model_reasoning_effort = "xhigh"
web_search = "live"
[profiles.fast] # cheap iteration
model = "gpt-5-codex-mini"
model_reasoning_effort = "medium"Switch profiles with codex --profile <name> at the codex CLI level. magic-codex passes through to the codex MCP server, which honors your codex config — no magic-codex changes needed when you adjust profiles.
When to pin a model in magic-codex.toml: only when you want a role to diverge from your codex default. The most common case is budget-capping the generic role:
[roles.generic]
model = "gpt-5-codex-mini" # cheap for repetitive workPer-spawn overrides remain available:
{
"role": "reviewer",
"prompt": "...",
"overrides": { "model": "gpt-5.5", "timeout_seconds": 1200 }
}See magic-codex.toml.example for a copy-paste starter and a richer set of profile recommendations.
/magic-codex:review-pr 456
- Plugin runs
gh pr view 456 --json headRefOid,headRefName,baseRefName,title,url. - Creates a detached git worktree at the PR's head SHA under
.magic-codex/worktrees/<agent_id>. - Starts Codex with
sandbox: read-only,cwd= that worktree, plus PR context injected intodeveloper_instructions.
The reviewer now has a real filesystem checkout — can grep, read tests, inspect code context — not just a diff blob. Pair with your own review (Claude directly or a separate review skill) for two independent perspectives.
Auto-activated when .magic-flow/ or ops/workers.json exists at repo root. When active:
- Linear enrichment — if
LINEAR_API_KEYis set and you passissue_id, the issue title / description / URL populate prompt placeholders. - Branch naming —
feature/TEAM-NNN-<slug>instead of the plaincodex/<suffix>fallback. - Conventions injection — the plugin reads your
~/.claude/CLAUDE.md"Magic Flow Workflow Conventions" section and injects it into every Codex spawn so agents follow your branch / commit / Linear rules. - Worker registry mirror — every status transition upserts into
ops/workers.jsonusing an MF-compatible schema;/mf-statuspicks it up for free.
To opt out: remove those markers. The plugin works cleanly outside MF projects.
.magic-codex/state.json(gitignored) — agent registry, status,thread_ids, worktree info. Survives MCP restarts..magic-codex/worktrees/<agent_id>/— per-agent worktrees. Preserved after completion until/magic-codex:mergeor/magic-codex:discard.ops/workers.json— MF-mode worker registry mirror.
All files optional. Merged in this order (highest precedence last):
src/roles/defaults/*.toml(built-in)~/.magic-codex/config.toml(user-global)<repo>/magic-codex.toml(project-committed)<repo>/.magic-codex/roles.toml(project-personal, gitignored)- Per-spawn
overrides
Full example — magic-codex.toml.example.
npm install
npm test # 62 unit tests, ~3s
npm run typecheck # strict TS
npm run build # compile + assets
./scripts/smoke-tools-list.sh # verify MCP server lists all 9 tools
# Optional — integration test against real codex (requires auth):
RUN_CODEX_INTEGRATION=1 npm testProject layout:
src/
├── index.ts # MCP server entry (stdio)
├── orchestrator.ts # spawn/resume/cancel/merge/discard lifecycle
├── registry.ts # persisted agent state
├── worktree.ts # git worktree create/remove/merge/detached
├── roles/ # TOML presets + loader + templater
├── mcp/codex-client.ts # MCP client → codex mcp-server
├── mf/ # Magic Flow integration (detect, linear, workers, github, conventions)
├── delegation.ts # minimal / balance / max policy
└── types.ts
commands/ # slash commands (markdown)
agents/ # subagent definitions (markdown)
docs/plans/ # design + implementation plans
tests/unit/ # 62 unit tests
Full architecture: docs/plans/2026-04-24-magic-cc-codex-worker-design.md.
- Implementer role uses
sandbox: workspace-write— Codex can write files in the worktree but is kept out of the main tree. Usedanger-full-accessonly if you really know what you're asking for. - Review every worktree diff before
/magic-codex:merge. - The plugin never pushes to remotes on its own. PR creation is deliberately left to the user.
- The plugin never talks to Linear or GitHub unless you've provided credentials (
LINEAR_API_KEY,gh auth).
How is this different from the official OpenAI Codex plugin for Claude Code?
The official plugin lets you run a single Codex session from inside Claude Code. This plugin is a full multi-agent orchestration layer — parallel Codex workers in isolated git worktrees, role-based specialization (implementer / reviewer / planner), resumable sessions via Codex's native thread_id, and dual-model PR review. See the comparison table above.
Does this work with GPT-5 and GPT-5-codex?
Yes. Each role defaults to whatever model your ~/.codex/config.toml selects, and you can override per-role (in magic-codex.toml) or per-spawn (via the overrides.model argument). Any model the codex CLI accepts works.
Do parallel Codex workers conflict on the same files?
No. Every implementer-role worker runs in its own git worktree on its own branch. Three workers can edit the same file in three different ways and never see each other's changes. You review each diff and /magic-codex:merge the winner.
Can I use this in a commercial project?
See LICENSE and COMMERCIAL.md. The plugin is under PolyForm Noncommercial 1.0.0 — free for independent developers, research, education, and nonprofits; commercial use requires a separate license (low-friction — open a GitHub issue labeled commercial-license). Most commercial requests are approved quickly.
Does the plugin require a git repository to work? Only for implementer / planner roles (they use git worktrees). Reviewer and generic roles run fine outside a repo. If you try to spawn an implementer outside a repo, the plugin errors clearly.
How do I stop a Codex worker that's gone off the rails?
/magic-codex:cancel <agent_id> kills the subprocess and marks the worker cancelled (not failed — the distinction is preserved). The worktree is kept for inspection unless you add --force.
Do I need to install Node.js or npm to use the plugin?
No. The plugin ships a single-file bundled MCP server (plugin/dist/index.js). The only runtime prerequisite is the codex CLI itself. Node is only required if you want to develop / modify the plugin.
What's the "delegation level" and why would I change it?
A policy knob that tells Claude how aggressively to offload work to Codex instead of doing it itself. minimal = prefer Claude; max = Claude becomes the orchestrator and routes everything Codex can handle to it. Run /magic-codex:mode <level> to set it user-globally. Useful when Claude quota is running low.
Does this integrate with Linear or GitHub Issues?
The plugin auto-detects Magic Flow projects and enriches agent context with Linear issue details when LINEAR_API_KEY is set and issue_id is passed. Plain GitHub Issues aren't first-class but the reviewer's PR-worktree mode uses gh pr view so GitHub PRs are fully supported.
See CONTRIBUTING.md. Tests required; strict TypeScript; small PRs.
PolyForm Noncommercial 1.0.0 © 2026 Wenqing Yu.
- Free for independent developers, hobby projects, research, education, and nonprofits — use, modify, redistribute freely, as long as attribution is preserved.
- Commercial use (for-profit companies, SaaS integrations, reselling, or public distribution of derivative products) requires a separate license. See COMMERCIAL.md for how to request one — most cases are fast and friendly.
- Derivative work / substantial idea borrowing: please reference this project in your README (
Based on magic-cc-codex-worker by Wenqing Yu). It's appreciated, and required under the license when you copy substantial code.
If in doubt — open an issue and ask. We'd rather approve a use case than turn anyone away for paperwork.
Part of Magic Stack — an agent-autonomous development stack for production-ready projects. This plugin is its multi-agent bridge between Claude Code and the Codex ecosystem.