codex-router

codex-router — route heavy Claude Code (Fable 5) tasks to OpenAI Codex (GPT-5.6)

codex-router is a Claude Code plugin that lets your Claude agent delegate heavy-duty coding work to OpenAI Codex, selecting GPT-5.6 Sol, Terra, or Luna for the task and running it non-interactively in the background — while Claude writes the brief, supervises the run, reviews the diff, and verifies the result before it reaches you.

Claude is a brilliant orchestrator, but some tasks are a big mechanical grind: sweeping refactors, bulk migrations, fixing forty similar test failures, generating boilerplate from a spec. codex-router turns Claude Code and Codex into a two-agent team with one workflow:

Claude thinks. Codex grinds. Claude checks.

Table of contents

• Features
• Prerequisites
• Installation
• Usage
• How it works
• Configuration
• Safety and privacy
• FAQ
• Contributing
• License

Features

• /codex skill for Claude Code — invoke explicitly, or let it trigger naturally on phrases like "offload this to Codex" or "send the heavy part to GPT-5.6 Sol".
• Model-aware routing — Claude picks GPT-5.6 Sol for difficult work, Terra for balanced everyday implementation (the default), and Luna for bounded high-throughput tasks. An explicit model choice or CODEX_ROUTER_MODEL remains authoritative.
• Supervised delegation, not fire-and-forget — Claude reviews the actual diff (never just Codex's summary), runs the definition-of-done checks, and fixes or re-briefs.
• Background execution — Codex runs via codex exec while Claude keeps working; no blocked terminal, no babysitting.
• Resumable sessions — follow-up corrections continue the same Codex session with full memory of the prior run, instead of relaunching cold.
• Auditable runs — every run leaves a directory with the exact prompt sent, the full JSONL event stream, Codex's final message, and the session id.
• Safe defaults — workspace-scoped sandbox, network off, no commits or pushes by the worker; escalation only with your explicit approval.
• Parallel offloads — independent subtasks fan out across git worktrees.

Prerequisites

• Claude Code (CLI, desktop, or IDE extension)

• OpenAI Codex CLI, installed and logged in:

  npm install -g @openai/codex
  codex login
  

  GPT-5.6 routing requires Codex CLI 0.144.0 or newer.

Installation

As a Claude Code plugin (recommended):

/plugin marketplace add luckeyfaraday/codex-router
/plugin install codex-router

Or manually, by copying the skill into your user skills directory:

git clone https://github.com/luckeyfaraday/codex-router
cp -r codex-router/skills/codex ~/.claude/skills/codex

Usage

Invoke it explicitly:

/codex migrate every route in src/api/ from Express 4 error handling to the new middleware style

Or just describe the intent in plain language:

> This refactor touches ~80 files. Offload the mechanical part to Codex and review what comes back.

Good candidates to route to Codex: large refactors and renames, framework/API migrations, bulk lint or test-failure fixes, boilerplate-heavy features from a clear spec. Claude keeps for itself anything small, ambiguous, architectural, or touching secrets.

How it works

1. Brief — Claude writes a self-contained task spec (goal, file paths, numbered requirements, definition of done, out-of-scope list), because Codex starts with zero conversation context.
2. Route and launch — Claude selects GPT-5.6 Sol, Terra, or Luna for the work, then the bundled wrapper runs codex exec in the background with the selected model, appropriate reasoning effort, a workspace-write sandbox, network off, and JSONL event logging.
3. Review — when the run exits, Claude reads the real diff, runs the tests/checks from the definition of done, fixes small gaps itself, or resumes the Codex session with corrections.
4. Report — Claude tells you what was offloaded, what came back, and what was verified.

Configuration

Environment variables read by the wrapper script (skills/codex/scripts/run-codex.sh):

Per-run flags (-m, -e, -s, --network, --resume, -C) override the environment; see the header of run-codex.sh.

The built-in GPT-5.6 routing choices are:

Availability depends on the Codex account and workspace. If the chosen GPT-5.6 model is not available, update Codex first and then choose a model the account can access.

Safety and privacy

• Codex runs sandboxed to the target workspace with network access off by default; Claude enables --network (or asks you about danger-full-access) only when a task genuinely needs it.
• The worker is instructed to never commit or push — you and Claude review the working-tree diff first.
• Briefs never include secrets, tokens, or .env contents.
• Code in the offloaded task's scope is sent to OpenAI via your own Codex CLI login, under whatever plan and data-controls that account has. Don't route code you wouldn't open in Codex directly.

FAQ

What is codex-router? A Claude Code plugin (a skill plus a wrapper script) that lets Claude delegate large, well-specified coding tasks to OpenAI Codex with model-aware GPT-5.6 routing, then review the results.

Can Claude Code use GPT-5.6? Not natively — Claude Code runs Claude models. codex-router bridges the two: Claude stays your primary agent and drives the OpenAI Codex CLI as a background worker, so you get GPT-5.6's capabilities with Claude's supervision.

Do I need both subscriptions? Yes — a Claude plan for Claude Code and an OpenAI/ChatGPT plan (or API key) for the Codex CLI. codex-router itself is free and open source.

Does this replace Claude Code subagents? No. Subagents are more Claude; this is a different model for the grind work, useful when you want a second opinion, different strengths, or to spend OpenAI quota instead of Claude quota on mechanical tasks.

Which models can the worker use? Any model your Codex CLI can run. The skill routes by default among gpt-5.6-sol, gpt-5.6-terra (the default), and gpt-5.6-luna; set CODEX_ROUTER_MODEL or pass -m to use another available model. If you adapt the wrapper, it can also use open-weight local models via Codex's --oss provider.

What happens if Codex gets it wrong? Claude catches it in review — it diffs and tests before reporting — then either fixes small gaps itself or resumes the same Codex session with corrections (sessions keep full memory).

Is my code safe? The worker is sandboxed to the workspace with no network by default and never commits. Code within the task's scope does go to OpenAI's API through your own Codex login — see Safety and privacy.

Contributing

Issues and PRs welcome — see CONTRIBUTING.md. Good first contributions: support for more worker CLIs, smarter run monitoring, additional briefing templates.

License

MIT © luckeyfaraday

Keywords: Claude Code plugin, Claude Code skill, delegate to Codex, OpenAI Codex CLI, GPT-5.6 Sol, GPT-5.6 Terra, GPT-5.6 Luna, multi-agent coding, AI agent orchestration, Claude + Codex workflow, offload coding tasks, AI pair of agents.