Codex Hybrid Worker Router

Use Luna Max where the subagent runtime supports it, with a Terra Max compatibility fallback, without giving up Sol-level quality gates.

简体中文 · License · Changelog

The 30-second mental model

• Default: ordinary Codex behavior. Every new chat starts here.
• Hybrid: only the current chat uses Luna Max or Terra Max for bounded work, while Sol xhigh keeps the quality gates.
• The router chooses the worker. You keep describing tasks normally.
• You can return the current chat to Default at any time.

Switch one chat to Hybrid:

$codex-hybrid-worker-router:hybrid

Return that chat to standard Codex behavior at any time:

$codex-hybrid-worker-router:default

The choice affects only the current chat. New chats still start in Default.

What Hybrid does

• Luna Max handles clear, bounded, low-risk searches, transformations, mechanical edits, known-root-cause fixes, targeted tests, and prechecks when it is registered for subagents.
• If the current subagent runtime does not register Luna, Hybrid uses Terra Max for the same restricted work. This is an internal fallback, not a third user mode.
• Sol xhigh handles architecture, ambiguous requirements, cross-module or unknown-root-cause debugging, concurrency, security, auth, permissions, migrations, destructive actions, authoritative review, and final synthesis.
• The economy worker escalates to Sol on uncertainty, scope expansion, unexplained failures, shared-contract changes, or high-risk signals.
• At most one writer runs at a time. A writer never runs beside another agent.
• Exploration, writing, and verification run as separate phases. Independent review, when required, starts only after the writer exits and uses a stable snapshot marker.
• Review and validation start at zero: read-only work gets none; behavior-neutral mechanical edits get scope self-check only; low-risk local behavior changes get at most a lightweight diff check and one cheap directly relevant test when available.
• Ordinary sol_worker output is accepted from its delivery summary and necessary evidence without duplicate rereading, test reruns, or sol_reviewer.
• Broader tests and independent review are reserved for concrete high-impact risk or an explicit user request; full suites are not a normal milestone default.
• Findings are deduplicated, unchanged failures are not retried, and unmet external prerequisites or required user input stop execution instead of causing polling loops.
• Two unsuccessful High/Medium fix-verification cycles trigger architectural replanning or a user decision rather than an unbounded patch loop.
• No worktrees are created or switched.

This approach aims to reduce expensive Sol usage. Luna usually offers the largest saving; Terra fallback saves less but avoids a failed task and preserves the same Sol quality gates. It does not promise fewer total tokens: subagents and Max reasoning can increase token volume.

If Luna says “not registered”

Top-level model selection and subagent model registration are separate capabilities. Seeing Luna under /model proves that a new top-level task can use it; it does not prove that the current subagent spawn tool can.

Hybrid inspects the models advertised by the subagent tool before its first low-cost delegation. If gpt-5.6-luna is absent or a spawn returns an unknown/unregistered/unavailable-model error, it does not retry Luna in that chat. It uses Terra Max when registered, or keeps the task on the primary Sol when neither economy model is available. Sol-only work remains Sol-only.

For manual diagnosis, ask Codex: “Report the models registered by the current subagent spawn tool; do not start an agent.” Restart in a new chat after updating Codex or changing account/host, because model catalogs can differ by surface, host, account, and session.

Install with Codex — recommended

Requirements: Codex CLI and Python 3.9+.

Open a Codex chat and paste this entire prompt:

Install Codex Hybrid Worker Router from:
https://github.com/YHK-AI/CodexHybridWorkerRouter

Requirements:
1. First inspect README.md, setup.py, and the plugin manifest read-only. Confirm that the source is YHK-AI/CodexHybridWorkerRouter.
2. Keep the repository in a stable location:
   - macOS/Linux: ~/.codex/community/CodexHybridWorkerRouter
   - Windows: %USERPROFILE%\.codex\community\CodexHybridWorkerRouter
3. If that directory already exists, verify that its origin matches this repository and that it has no uncommitted changes. Update only with git pull --ff-only; never overwrite local changes.
4. Run the platform-appropriate setup.py install command with --lang auto.
5. Run setup.py status and verify Marketplace, Plugin, and Global hardening are all installed.
6. Do not modify any project repository and do not create a worktree.
7. When finished, tell me to start a new Codex chat and show the exact Hybrid and Default commands.

Codex will inspect the package, clone it to a durable location, install it, verify it, and report the next step.

Manual full install

Clone the repository:

git clone https://github.com/YHK-AI/CodexHybridWorkerRouter.git
cd CodexHybridWorkerRouter

Or download the GitHub ZIP and open a terminal in the extracted directory. Then install:

macOS / Linux:

python3 setup.py install --lang auto

Windows PowerShell:

py -3 setup.py install --lang auto

--lang auto installs Chinese global routing rules for a Chinese locale and English rules otherwise. You can force --lang zh-CN or --lang en.

Start a new Codex chat after installation. Open the Skills menu and choose:

• Codex Router: Hybrid / 混合模式
• Codex Router: Default / 默认模式

The skills themselves are bilingual and explicitly invoked; they never activate just because a task looks suitable.

Use it

Start a new Codex chat after installation.

To enable routing only for that chat, choose Codex Router: Hybrid / 混合模式 from the Skills menu, or enter:

$codex-hybrid-worker-router:hybrid

Then ask for work normally. For example:

$codex-hybrid-worker-router:hybrid
Find the cause of this failing test, implement the safest fix, run the targeted tests, and summarize the remaining risk.

You do not need to decide between Luna, Terra, and Sol. The router classifies and delegates the work. To turn custom routing off in the same chat, choose Codex Router: Default / 默认模式, or enter:

$codex-hybrid-worker-router:default

Every newly created chat still starts in Default.

Language support

Codex currently gives a skill one set of UI metadata rather than separate locale-specific labels. This package therefore uses bilingual names and descriptions in the Skills menu, English as the canonical machine-facing routing language, and separate English and Simplified Chinese READMEs. The installer can place either English or Chinese global rules according to locale or --lang.

Plugin-only install

For the fastest lightweight install, add the GitHub repository directly as a marketplace:

codex plugin marketplace add YHK-AI/CodexHybridWorkerRouter --ref main
codex plugin add codex-hybrid-worker-router@yhk-ai

Then start a new Codex chat. This installs the two self-contained mode skills, but not the named Agent TOMLs or global hardening. The full Codex-assisted setup.py install path is recommended for the complete behavior.

Uninstall

The easiest option is to paste this into Codex:

Uninstall Codex Hybrid Worker Router using the saved repository's setup.py uninstall --remove-marketplace command. Verify the result, preserve all recovery backups, do not modify project repositories, and tell me whether a new Codex chat is required.

macOS / Linux:

python3 setup.py uninstall --remove-marketplace

Windows PowerShell:

py -3 setup.py uninstall --remove-marketplace

Every global install/uninstall operation creates a recoverable backup under:

~/.codex/recovery-backups/codex-hybrid-worker-router/

Normal uninstall restores the exact snapshot from before the first installation. It also saves the current state immediately before restoring, so post-install changes remain recoverable. The installer refuses to overwrite same-named files it does not manage.

Normal uninstall does not require manual backup handling. For manual disaster recovery, close Codex and inspect the chosen timestamped backup before restoring its config.toml, AGENTS.md, and agents/*.toml; a *.was-absent marker means that file did not exist in the saved state. Keep the pre-restore state or ask Codex to assist rather than deleting files blindly.

Keep this folder, or keep the repository URL, until you uninstall; setup.py is the portable uninstall entry point.

Repository layout

.
├── .agents/plugins/marketplace.json
├── plugins/codex-hybrid-worker-router/
├── README.md
├── README.zh-CN.md
└── setup.py

Keep the marketplace root and plugins/ directory together. The plugin folder alone does not include the repository installer.

Security model

• Default mode leaves ordinary Codex behavior untouched.
• Hybrid must be selected explicitly in the current chat.
• Security, migrations, destructive actions, and irreversible operations require Sol planning, an independent Sol preflight, concrete authorization, a single Sol executor, and proportionate primary-Sol verification.
• A second independent review is not automatic after Sol execution; add it only when implementation departed from the reviewed plan, changed a shared contract or security boundary, or the user explicitly requested it.
• Using Sol never grants authority by itself.

License

MIT. See LICENSE.