Skip to content

README.en.md

Latest commit

 

History

History
192 lines (130 loc) · 6.4 KB

README.en.md

File metadata and controls

192 lines (130 loc) · 6.4 KB
Raw

codex-model-router

繁體中文｜English

Installs an evidence-first Codex workflow for Terra, Luna, and Sol while preserving the user's primary model and unrelated Codex configuration.

Routing is advisory. Codex reads the installed agents and skills and decides when to delegate. This package does not intercept prompts or guarantee a hard model switch.

Install

Project:

npx codex-model-router@latest install

Current user:

npx codex-model-router@latest install --global

Enable package-managed multi-agent V2:

npx codex-model-router@latest install --v2

Use --global --v2 for the current user. Restart Codex after installation.

Codex installation locations

Scope Agent definitions User skills
Project <project>/.codex/agents <project>/.codex/skills
Current user ~/.codex/agents ~/.codex/skills

Skills are installed under .codex/skills/<skill-name>; reinstalling safely migrates package-managed legacy skills and prints the resolved paths.

Configuration

npx codex-model-router@latest install \
  --terra-reasoning medium \
  --luna-reasoning xhigh \
  --sol-reasoning medium \
  --terra-fast

When --terra-reasoning is omitted, managed Terra children default to medium.

Option Purpose
--set-default Set Terra/high as the primary default
--agent-reasoning <level> Set reasoning for all managed agents
--terra-reasoning <level> Set Terra reasoning
--luna-reasoning <level> Set Luna reasoning
--sol-reasoning <level> Set Sol reasoning
--agent-fast / --no-agent-fast Set Fast preference for all managed child roles; role options take precedence
--terra-fast / --no-terra-fast Set Terra Fast preference
--luna-fast / --no-luna-fast Set Luna Fast preference
--sol-fast / --no-sol-fast Set Sol Fast preference
--v2 Enable or repair package-managed V2
--global Apply the installation to the current user

Reasoning values: none, low, medium, high, xhigh, max.

Fast and reasoning are independent and retained only for the same child role. Use status [--global] to view them; Codex currently has no per-child Fast runtime control, so configured=true reports effective=not-supported.

Visual guides

All diagrams are collapsed by default. Select a heading to expand it.

Roles, models, access, and responsibilities

Codex Model Router role diagram

Standard main workflow overview

Codex Model Router main workflow overview

Plan-artifact persistence and cleanup 
flowchart TD
    A[Terra or Sol returns plan content] --> B{Active writable executor?}
    B -->|No| C[Keep a self-contained in-memory artifact\nDo not claim a file write]
    B -->|Yes| D[Atomically write\n<CODEX_ROOT>/model-router/workflows/<workflow_id>/PLAN.md]
    D --> E[State: active\nRecord plan_path and owner]
    E --> F{Verification PASS?}
    F -->|No, blocked, resume, or switch| G[Preserve path, version, and owner]
    F -->|Yes| H[State: pending-cleanup]
    H --> I[Same cleanup owner\nRemove only this workflow directory]
    I -->|Success| J[State: removed]
    I -->|Failure| K[State: cleanup-failed and report it]
Loading
Estimated model usage share

Estimated model usage share

Primary-model Q&A outside the workflow

Primary-model Q&A scenarios

Scenario A: Primary is Sol

Sol primary workflow

Scenario B: Primary is Terra

Terra primary workflow

Scenario C: Primary is Luna

Luna primary workflow

Core rules

  • The same model is not spawned twice in one workflow.
  • A matching primary model performs that role in the primary thread.
  • Stage and Luna mode gate writes; luna_execution_enabled is migration-only and cannot replace the mode.
  • Terra plans and independently verifies; Sol joins after a non-PASS result.
  • Luna keeps the same luna_role_id for the root session/workflow; after demotion it runs only stage-authorized canonical action IDs as INTERACTION_ONLY.
  • The final response always returns through the primary model.

Multi-Agent Workflow Overview

Multi-Agent Workflow Overview

V2

install --v2  → enable V2; repair a modified or missing tracked marker block
install       → disable unchanged package-managed V2
uninstall     → remove the router and unchanged managed V2

When install --v2 is explicitly run again and package state still exists, a changed or missing package-marked V2 block is rebuilt, its hash is updated, and unrelated TOML is preserved. Pre-existing unmanaged V2, missing state, incomplete markers, or duplicate markers remain preserved and stop the operation to prevent accidental overwrites.

Remove

Project:

npx codex-model-router@latest uninstall

Current user:

npx codex-model-router@latest uninstall --global

Safety

  • Preserves unrelated TOML, comments, BOM, ordering, and LF/CRLF.
  • Uses path validation, scope locking, atomic transactions, and rollback.
  • Except for rebuilding the package-marked V2 block after an explicit install --v2, it never overwrites other user-modified managed files.
  • Never changes AGENTS.md, shell profiles, editor settings, hooks, MCP servers, accounts, telemetry, or environment variables.

Requirements

  • Node.js 18 or newer.
  • Codex with custom-agent and local-skill support.
  • Access to gpt-5.6-terra, gpt-5.6-luna, and gpt-5.6-sol.
  • Windows, Linux, or macOS.

Security issues: see SECURITY.md. Maintainer release steps: see MAINTAINERS.md.