Codex Orchestra

Codex Orchestra installs a low-overhead, multi-model workflow into Codex. Sol Medium is the durable daily coordinator, Spark is a specialist for selected simple bounded work, Luna Max is the read-only explorer, and Sol handles review and expert judgment.

The installed agents keep generic role names: explorer, fast_worker, worker, reviewer, and expert.

Install

After the package is published:

npx --yes codex-orchestra install

From a checkout:

node plugin/skills/manage-orchestration/scripts/cli.mjs install

The installer requires Luna and Sol. The Luna Max explorer and worker roles are always available; Spark's fast_worker is added automatically when available.

On Windows, Codex command shims are invoked through the system command processor. If the Codex CLI is not on PATH but %USERPROFILE%\.codex\models_cache.json exists, the installer still configures the runtime agents and reports that the optional management plugin was skipped. Add the Codex CLI to PATH and run npx --yes codex-orchestra update to register the plugin later.

Restart Codex or open a new task after installation.

What it changes

• Sets the managed Sol coordinator defaults, global compaction policy, multi-agent v2 settings, concurrency, and depth without replacing unrelated configuration.
• Installs each role's model, reasoning, summary, and compaction settings exactly as defined by the package templates.
• Adds a managed routing block to the active global AGENTS.md or AGENTS.override.md.
• Installs role files in $CODEX_HOME/agents.
• Registers a local Codex plugin containing the management skill.
• Records ownership and update backups under $CODEX_HOME/orchestration.

Unrelated configuration is preserved. Existing generic agent files cause a safe failure unless --force is explicitly supplied; forced replacements are backed up and restored on uninstall.

The plugin is optional at install time. It provides the in-Codex management skill for doctor, update, and uninstall operations; the runtime orchestration itself comes from config.toml, the agent files, and the managed AGENTS.md guidance. Use --skip-plugin when only those runtime surfaces are wanted.

Manage

npx --yes codex-orchestra doctor
npx --yes codex-orchestra update
npx --yes codex-orchestra uninstall

The installed $manage-orchestration skill can run the same commands from inside Codex.

Useful options:

• Spark is enabled automatically when gpt-5.3-codex-spark is available; machines without it use the fallback agent set.
• Long-horizon tasks are decomposed into research, implementation, and validation tracks; test and smoke execution can be delegated before Sol makes the final decision.
• --dry-run
• --force
• --codex-home <path>
• --json

The package follows Codex's documented custom-agent configuration and plugin structure. The plugin supplies management; the installer is required because plugins do not own global Codex configuration or global agent files.