Codex-Orchestration Deep Dive: One Plugin, Four Roles, Infinite Teamwork

Core idea: "You don't need a single more powerful model — you need a better collaboration framework." Codex-Orchestration pushes multi-model cooperation to its extreme: Planner uses Fable 5 to plan, Advisor uses Opus 5 to review, Designer uses Kimi K3 to design, and Executor uses GPT-5.6 Luna to implement. Codex remains the boss, but now the right AI handles the right job.

I. What Is It? (Explained for Absolute Beginners)

Imagine you're running a team coding project — but your team isn't made of people. It's made of AI assistants.

Normally, you only hire one AI assistant. It has to be the project manager, the designer, the coder, and the QA tester all at once. The result? The project manager rushes into coding without thinking hard enough. The designer's output isn't polished. The QA gets forgotten in the rush.

Codex-Orchestration is like a smart team-management plugin for Codex (OpenAI's AI coding assistant). It doesn't replace your AI assistant — it hires more AI assistants, each specializing in one job:

• Planner — Turns your request into a detailed execution plan. Think of it as the project manager drawing the roadmap.
• Advisor — Reviews the plan, finds gaps, makes sure nothing slips through. Like a quality manager catching bugs before code is written.
• Designer — Creates UI/UX designs, ensuring the product looks good and works well.
• Executor — Actually writes the code to implement the approved plan.

The coolest part: Each "assistant" can be a different model from a different company:

• Planner → Claude Fable 5 (great at planning)
• Advisor → Claude Opus 5 (great at reviewing)
• Designer → Kimi K3 (massive 1M token context)
• Executor → GPT-5.6 Luna (fast at implementing)

And your original Codex AI stays as the CEO — deciding when each specialist joins, collecting their work, and signing off on the final result.

II. Project Overview

2.1 Basics

2.2 The Problem It Solves

Problem 1: One Model Can't Do Everything Well

When you ask Codex to do a complex task, it must wear many hats:

1. Understand requirements → 2. Plan the solution → 3. Review for risks → 4. Write code → 5. Test & verify

A single model is mediocre at each stage. GPT-5.6 Sol might have great planning intuition but miss edge cases in review. Fable 5 excels at reviewing details but isn't the fastest at implementation.

Problem 2: Model Selection Is Locked to ChatGPT/OpenAI

Codex's native interface only lets you pick models registered on the ChatGPT/OpenAI platform. Want to use Anthropic's Claude or OpenRouter's Kimi K3? Those "external models" normally can't be wired into Codex's workflow.

Problem 3: No Independent Review Mechanism

The most dangerous scenario in multi-model collaboration is self-review — the planner reviewing its own plan. Codex-Orchestration enforces strictly that Planner and Advisor MUST use different models, guaranteeing independent review every time.

Problem 4: Credential Security

Pasting an API key into chat, or writing it to a config file, is a massive security risk. Codex-Orchestration implements a security checkpoint system — credentials never appear in chat logs or code repositories.

2.3 Core Features

III. Core Ideas

3.1 The Four-Role System

Codex-Orchestration introduces four specialist roles into a Codex task, each responsible for one phase of the development lifecycle:

🎯 Planner

• Responsibility: Translates user requirements into a detailed execution plan
• Workflow: Receives request → creates plan → receives Advisor feedback → improves plan
• Optional: If omitted, the current Codex model serves as Planner
• Example models: Claude Fable 5, GPT-5.6 Sol

🔍 Advisor

• Responsibility: Reviews the plan for gaps, risks, and technical pitfalls
• Workflow: Receives plan → identifies issues → returns PLAN_APPROVED or PLAN_REVISE
• Optional: If omitted, no review stage occurs
• Example models: Claude Fable 5, Claude Opus 5, GPT-5.6 Sol
• Limit: Maximum 8 review rounds — stops execution if not approved

🎨 Designer

• Responsibility: Turns the approved plan into design assets (UI/UX, interaction design, info architecture)
• Workflow: Receives plan → produces design files → passes to Executor
• Optional: If omitted, no design stage occurs
• Example models: GPT-5.6 Terra, Kimi K3 (external)

⚙️ Executor

• Responsibility: Implements the approved plan in code
• Workflow: Receives plan + design → implements → delivers
• Required: Always must be specified
• Example models: GPT-5.6 Luna

3.2 Workflow

                         YOUR TASK
                             |
                             v
                  CODEX COORDINATES THE WORK
                             |
                             v
               PLANNER CREATES THE FIRST PLAN
               Fable 5, another model, or Codex
                             |
                             v
                    ADVISOR REVIEWS IT
                       finds real gaps
                             |
                   needs work? -- yes --+
                             |            |
                            no            v
                             |      PLANNER IMPROVES IT
                             |            |
                             +<-----------+
                             |
                       PLAN APPROVED
                             |
                             v
                DESIGNER SHAPES THE EXPERIENCE
                (optional design handoff)
                             |
                             v
                  EXECUTORS IMPLEMENT IT
                             |
                             v
                    CODEX TESTS & DELIVERS

Key rule: Planner and Advisor must use different models. This is the core safeguard that ensures "independent review."

3.3 Design Philosophy

Philosophy 1: Codex Is Always the Boss

"The model selected for the Codex task remains in charge."

Codex-Orchestration never replaces Codex itself. It only brings more models in as "assistants." Codex remains:

• The one that decides how to decompose tasks
• The one that chooses when each assistant steps in
• The one that collects all results
• The one that does final validation & delivery

Philosophy 2: Preview First, Fail-Closed

All operations follow the "Preview → Confirm → Apply" flow:

# Preview (makes no changes)
python3 configure_native_routing.py --codex-bin <path> --status

# Apply
python3 configure_native_routing.py --codex-bin <path> --status --require-effective

If any check fails, the system stops immediately rather than proceeding. This "fail-closed" design ensures security boundaries aren't accidentally breached.

Philosophy 3: Credentials Are Never Stored

"Never paste an API key into Codex chat. The repository, provider TOML, registry, journal, logs, and tests store no key."

The project enforces a strict rule: API keys must never appear anywhere visible. Credential handling works like this:

1. Preparation phase: A hidden local prompt in a trusted terminal
2. Storage: OS credential store (macOS Keychain / Linux Secret Service / Windows Credential Manager)
3. Retrieval: Only fetched at request time when an API call is needed
4. Forbidden everywhere: chat logs, config files, source code, Git, logs, tests, registry — none ever store the key

Philosophy 4: Routing Is Policy-Guided, Not Engine-Enforced

"Same-provider routing could be mistaken for an engine-enforced executor selector."

Routing is policy-guided, meaning:

• Codex can still choose not to delegate
• The model parameter is a "suggested" route, not a hard mandate
• If routing fails, Codex falls back to the root model

Philosophy 5: Principle of Least Privilege

Every role has clearly defined permission boundaries:

• Planner: Can plan only; cannot edit code
• Advisor: Can review plans only; cannot execute or edit
• Designer: Can edit only design artifacts; cannot modify implementation code
• Executor: Can implement the plan; does not interfere with other roles
• Claude subprocesses: no-tools, no-persistence, minimal environment

IV. Key Findings & Conclusions

4.1 Five Lessons from the Production-Readiness Audit

The project underwent a formal production-readiness audit on July 12, 2026. The audit found and fixed several issues:

Conclusion: The project started with a hard question — "how do we make complex routing tech both safe and usable?" — and solved it through rigorous auditing and iteration.

4.2 Three Routing Methods

Conclusion: The plugin provides a complete "model access pyramid" — from the simplest same-provider direct routing to the most stringent external model integration.

4.3 Kimi K3's Credential Security Architecture

Kimi K3 (via OpenRouter) is the most representative "external model" case in this project. It demonstrates the full security architecture:

1. Provider Preparation: Only adds [model_providers.openrouter] and command-backed auth table
2. Authentication: OS credential store + hidden local prompt (never paste keys in chat)
3. Gate 0 Probe: One paid, isolated probe to verify the model actually works
4. Role Creation: Creates provider-pinned personal agent variants
5. Sealed Execution: Uses codex exec direct CLI call with all tools disabled

Critical point: Every installation starts "unqualified" until it passes one explicitly billable isolated Gate 0. You can't "steal" unbilled model access.

4.4 Version Evolution Timeline

From the CHANGELOG, we can trace a clear evolution:

• v0.1–v0.3 (Jul 9): Basic advisor workflow; secure external model roles
• v0.4 (Jul 10): Config-first routing becomes the primary workflow; v2 spawn metadata support
• v0.5.1 (Jul 16): Planner role added; Fable 5 supports Planner + Advisor simultaneously
• v0.6.0 (Jul 18): External models (Kimi K3), OS credential store, Gate 0 probe — security foundation complete
• v0.7–v0.72 (Jul 18): Designer role; --update; concise activation confirmation
• v0.8.0 (Jul 18): Sealed direct CLI transport for READY external models
• v0.9.0 (Jul 25): Claude Opus 5 added; raised review ceiling from 5 → 8 rounds; security hardened

Conclusion: In just one month, the project went from v0.1 to v0.9 — each release fixing specific security or usability issues.

4.5 Engineering Craftsmanship

From the production-readiness audit's "Deliberate boundaries that remain" section, the designers showed meticulous attention to every attack surface:

1. External Model READY roles use sealed direct CLI transport, not Desktop native spawn-agent — preventing tool abuse
2. There is no engine-level executor selector — routing is always policy-guided; Codex retains final decision power
3. Direct model overrides inherit the root provider — cross-provider requires explicit configuration
4. Claude Fable 5 is a narrowly-scoped built-in exception — only as Planner/Advisor, never as Designer/Executor
5. "Any model" has precise boundaries — only models from Codex's provider, a configured compatible custom provider, or a deliberately bundled bridge. The plugin never creates accounts, credentials, or protocol compatibility.

Conclusion: At every decision point, the designers chose fail-closed over convenience-first. In the age of increasingly autonomous AI agents, this "trust but verify, convenience but security" philosophy may well be the standard for future multi-model collaboration.

V. Detailed Tutorial

5.1 Installation

First, install the Codex-Orchestration plugin into Codex:

# Install from marketplace
codex plugin marketplace add Cjbuilds/Codex-Orchestration

# Add the plugin to Codex
codex plugin add codex-orchestration@codex-orchestration

⚠️ Important: After installation, you must restart Codex and start a new task to activate the plugin.

5.2 Command Syntax

All operations are done through Codex prompts (not terminal commands). You type this format in the Codex chat:

$codex-orchestration:codex-orchestration <command>

For example, to check current status:

$codex-orchestration:codex-orchestration status

5.3 Configuring Roles (setup)

The setup command is the most important one — it maps each role to a specific model. Syntax:

$codex-orchestration:codex-orchestration setup \
  planner: <model and effort>, \
  advisor: <model and effort>, \
  designer: <model and effort>, \
  executor: <model and effort>

Example 1: Fable 5 plans, Sol reviews, Luna implements

$codex-orchestration:codex-orchestration setup planner: Claude Fable 5 High, advisor: GPT-5.6 Sol High, executor: GPT-5.6 Luna Extra High

Breakdown:

• Planner = Claude Fable 5 (effort: High) — planning
• Advisor = GPT-5.6 Sol (effort: High) — reviewing
• Executor = GPT-5.6 Luna (effort: Extra High) — implementing
• Designer = omitted (no designer configured)

Example 2: Full four-person team + Kimi K3 as designer

$codex-orchestration:codex-orchestration setup planner: Claude Fable 5 High, advisor: GPT-5.6 Sol High, designer: GPT-5.6 Terra High, executor: GPT-5.6 Luna Extra High

Example 3: Current Codex model plans, Fable 5 only as Advisor

$codex-orchestration:codex-orchestration setup advisor: Claude Fable 5 High, executor: GPT-5.6 Luna Extra High

5.4 Configuration Rules

• executor is required — determines who implements the plan
• planner is optional — if omitted, the current Codex model serves as Planner
• advisor is optional — if omitted, no review stage occurs
• designer is optional — if omitted, no design stage occurs
• Planner and Advisor must use different models — ensures independent review

5.5 Claude Fable 5 / Opus 5 Effort Options

Claude Fable 5 and Opus 5 can only be used as Planner or Advisor — never as Designer or Executor.

5.6 Querying External Model Availability

You can ask natural-language questions to check if external models are available:

is Kimi available to use as Designer?

The plugin checks the External Model registry and reports four distinct states:

1. supported: Kimi K3 is bundled and supported by the plugin
2. configured: Kimi K3 is configured on this installation
3. locally ready: Kimi K3 is ready to use in the current workspace
4. callable now: Kimi K3 has been verified callable via a sealed invocation

5.7 Configuring External Models (Kimi K3 Example)

If you want to use an external model like Kimi K3, you go through a staged process:

Step 1: Configure the External Role

$codex-orchestration:codex-orchestration configure external role researcher with OpenRouter model moonshotai/kimi-k3 at max; job: gather evidence and cite sources

Step 2: Authentication

The plugin displays a hidden local prompt in your terminal, guiding you to store the API key in your OS credential store. Never paste the API key into Codex chat!

Step 3: Gate 0 Probe

You must explicitly approve one potentially billable, isolated probe:

python3 <skill-dir>/scripts/external_configurator.py \
  --codex-bin <codex-binary-path> \
  gate0 --provider openrouter --model moonshotai/kimi-k3 --effort max --acknowledge-billing

This step incurs real API costs. Only run it after explicit confirmation.

Step 4: Create the Role

python3 <skill-dir>/scripts/external_configurator.py connect \
  --role researcher \
  --purpose "Gather evidence from the bounded packet and cite sources." \
  --provider openrouter \
  --model moonshotai/kimi-k3 \
  --effort max --apply

Step 5: Restart

After completion, you must restart Codex and start a new task for the role to load.

Step 6: Call the Role

$codex-orchestration:codex-orchestration call researcher at max — review this bounded research packet

5.8 Status & Maintenance

5.9 Designer: Kimi K3 Quick-Use Label

If Kimi K3 is already ready, you can use the shorthand seat-label syntax:

$codex-orchestration:codex-orchestration Planner: Claude Fable 5 High, Designer: Kimi K3

Designer: Kimi K3 maps automatically to role=designer, provider=openrouter, model=moonshotai/kimi-k3, effort=max. Important caveats:

• Kimi K3 only supports max reasoning; any other effort is rejected
• This shorthand does NOT add Kimi to the Codex Desktop model picker
• It does NOT replace any GPT route
• Cannot paste API keys in chat — cannot authorize Gate 0 paid probes

5.10 Using with Codex Goals

You can create a normal Codex Goal, then instruct Codex to use the saved workflow:

Please use the saved codex-orchestration workflow until this Goal completes.

Codex still manages Goal state, permissions, integration, and verification; the plugin only guides which model performs each role.

5.11 Security Operations

How to safely store credentials

1. Never paste an API key in Codex chat
2. Never write the key to config files, source code, Git, or logs
3. Correct method: Store via the OS credential store (macOS Keychain / Linux Secret Service / Windows Credential Manager)

If a key is compromised

disconnect and remove provider only delete exact plugin-managed role files and provider config. They never touch:

• Chats or sessions
• OpenAI authentication
• User-owned custom roles

VI. Installation & Development

6.1 Development Environment Setup

# Clone the repo
git clone https://github.com/Cjbuilds/Codex-Orchestration.git
cd Codex-Orchestration

# Install dev dependencies
python3 -m pip install -r requirements-dev.txt

# Compile & lint
python3 -m compileall -q plugins tests scripts
python3 -m ruff check plugins tests scripts

# Run tests
python3 -m unittest discover -s tests -v
python3 tests/plugin_lifecycle_smoke.py
python3 scripts/release_check.py

6.2 Version Requirements

• Python: 3.11+
• Codex Desktop: 0.144.0-alpha.4+ (for v2 spawn metadata)
• Claude Code: 2.1.219+ (for Opus 5 support)

VII. Conclusion

Codex-Orchestration is an innovative AI team management plugin. It doesn't merely solve "single-model capability limits" — it redefines what multi-model collaboration can look like through three key architectural principles:

7.1 Three Groundbreaking Principles

1. Role-based routing: Assign different models to Planner / Advisor / Designer / Executor, maximizing each vendor's strengths
2. Secure external model integration: OpenRouter + OS credential store + Gate 0 probe safely brings models like Kimi K3 into Codex
3. Policy-guided, not engine-enforced routing: Codex remains CEO; routing is a suggestion, not a mandate

7.2 Three Delivered Values

1. Stronger planning: Fable 5 is great at planning — delegate planning to it
2. Stricter quality control: Opus 5 is great at reviewing — independent review prevents self-review
3. Faster execution: Luna excels at fast implementation — and supports parallel execution

7.3 The Designers' Wisdom

From the production-readiness audit, the designers chose fail-closed over convenience-first at every attack surface:

• Credential security: Keys are never stored in chats, code, configs, Git, or logs — always via OS credential store
• Routing security: Cross-provider requires explicit configuration, preventing accidental unauthorized provider use
• Review security: Planner and Advisor must be different models — preventing "reviewing your own homework"
• Update security: Plugin self-update requires canonical source verification, preventing malicious replacement

This project demonstrates a mature approach to AI agent safety: not "what can we do?" but "what must we not do?" In an age where AI agents are becoming increasingly autonomous, this "trust but verify, convenience but security" design philosophy may well become the standard for multi-model collaboration.

VIII. Key Takeaways