claude-codex-orchestrator

claude-codex-orchestrator

Claude plans and verifies. Luna handles most bounded execution, Terra handles implementation judgment, and Sol handles the toughest work.

Why

Claude is the orchestrator and accepting judge. Codex is the execution surface. The router spends the narrowest capable model on each frozen packet:

• Luna Max for most fully specified, deterministic implementation;
• Luna Max Fast when latency materially matters;
• Terra High when localized implementation judgment remains;
• Sol High for architecture-sensitive, security, contract, concurrency, or other highest-risk work;
• Sol review/rescue for read-only review and stuck-task diagnosis.

Unresolved product and architecture decisions stay with Claude, as does final verification.

The loop

1. Plan — Claude resolves intent and decomposes the work.
2. Preflight — each cold packet is decision-complete and at most 12 KiB; source stays in the worktree and is referenced by path and symbol.
3. Dispatch — invoke one direct profile, or use the opt-in Sol-led orchestrated profile for a large frozen work order.
4. Execute — Luna routes to Terra when a decision appears; Terra routes to Sol at a high-risk boundary.
5. Review and verify — Codex may provide a read-only first review, but Claude inspects the diff and reruns the proof before accepting it.

The bounded packet preflight prevents the repeated oversized handoff and guessed chunk-size loop reported in issue #6.

Direct profiles

For one packet, call the selected profile directly. Do not launch a Sol coordinator merely to spawn one worker.

For a large frozen work order, --profile orchestrated activates a Sol coordinator that can route to five custom agents: luna_worker, luna_fast_worker, terra_implementer, sol-implementer, and sol-reviewer.

Prerequisites

1. Claude Code.

2. The OpenAI Codex CLI, authenticated with a ChatGPT Codex account.

3. The official OpenAI Codex plugin for Claude Code if you want /codex:setup and /codex:rescue:

   /plugin marketplace add openai/codex-plugin-cc
   /plugin install codex@openai-codex
   

The normal Luna, Terra, and Sol implementation lanes use direct codex exec --profile ... invocation. The companion cannot carry a profile, service tier, or Luna's max effort, so use it only where the skill explicitly permits it.

Install

When upgrading from the former daily / hard / mech layout, move only its nine replaced files out of Codex discovery first. This backup is recoverable and leaves every unrelated setting untouched:

legacy_dir=~/.codex/legacy-claude-codex-orchestrator
mkdir -p "$legacy_dir/agents"

for legacy_file in daily.config.toml hard.config.toml review.config.toml rescue.config.toml mech.config.toml escalate.config.toml; do
  test ! -e ~/.codex/"$legacy_file" || mv ~/.codex/"$legacy_file" "$legacy_dir/"
done

for legacy_agent in fast-worker.toml impl-worker.toml reviewer.toml; do
  test ! -e ~/.codex/agents/"$legacy_agent" || mv ~/.codex/agents/"$legacy_agent" "$legacy_dir/agents/"
done

Then install the current files:

mkdir -p ~/.claude/skills/codex-orchestrator
cp SKILL.md ~/.claude/skills/codex-orchestrator/SKILL.md
cp ROUTING.md ~/.claude/CLAUDE-CODEX-ROUTING.md

cp codex-profiles/*.config.toml ~/.codex/
mkdir -p ~/.codex/agents
cp codex-profiles/agents/*.toml ~/.codex/agents/

Merge the two keys from codex-profiles/config.base.example.toml only when they are missing; do not replace the rest of ~/.codex/config.toml.

A repository-local CLAUDE-CODEX-ROUTING.md overrides the global routing policy wholesale. The complete mechanics live in SKILL.md, and the installable global policy is ROUTING.md.

Examples

Frozen mechanical migration

"Rename getUser() to fetchUser() everywhere and update call sites" has no remaining design decision. Claude prepares one bounded packet and dispatches luna-worker. If latency materially matters, it selects luna-fast-worker instead.

Feature with localized judgment

"Implement the planned CSV export across these files" may leave serializer and error-handling choices inside an existing contract. Claude dispatches terra-implementer and verifies the resulting diff and tests.

Highest-risk implementation

A public API contract, auth boundary, or distributed coordination change routes to sol-implementer only after Claude freezes the intended contract.

Large frozen work order

Claude sends one bounded orchestration packet through --profile orchestrated. The Sol coordinator forwards exact sub-packets to Luna, Terra, or Sol, requests sol-reviewer, and assembles. Claude still gives the final verdict.

Oversized handoff

Claude writes the packet once, measures it locally, replaces pasted source and logs with file locators, and semantically splits it if necessary. It never calls Codex repeatedly with guessed chunk sizes.

Design principles

• Decision-complete, not source-complete. Codex reads the worktree.
• Luna by default for frozen execution. Terra handles judgment; Sol handles the highest risk.
• The transport must carry the lane. Report the model, effort, and service tier actually used.
• The diff is ground truth. Executor reports are claims until Claude reproduces them.
• No blind third retry. Escalate with evidence or decompose.
• Publication authority stays explicit. Workers do not commit, push, release, or mutate external systems unless separately authorized.

This project is separate from claude-router, which routes across Claude model tiers.

License

MIT © Vimox Shah