Astral Orchestrator
GitHub

Docs · Getting started

Install once. Start with a proven route.

The marketplace install is complete in two commands. Optional profiles improve named-agent ergonomics but do not grant model access or weaken exact-route checks.

Requirements

  • A current Codex CLI or desktop app with plugins enabled.
  • Access to Sol, Luna, or Astra for the primary and to each worker model selected for the run.
  • Python 3.11 or newer; the included local tools use only the standard library.
  • For Hypernova, native MultiAgentsV2 controls plus a supported exact child route.

Astral stops when an exact required model, effort, route, or review cannot be proven. It never silently substitutes another model or effort.

GitHub marketplace install

Run exactly these two commands in a terminal where Codex is available:

codex plugin marketplace add Demonbane18/astral-orchestrator --ref main
codex plugin add astral-orchestrator@astral-orchestrator

This is the complete install. Start a new Codex task afterwards so Codex discovers the plugin.

On current Codex MultiAgentsV2 hosts, delegated routes state agent_type, a unique task_name, model, reasoning_effort, and fork_turns explicitly. Optional profiles are not required. The bundled exact-process launcher is a legacy compatibility fallback only for modes that permit it and only on hosts missing one or more of those five native controls. Hypernova never permits that fallback.

Optional native-profile setup

For faster named-agent selection, download the public repository as a ZIP or clone the public repository, open a terminal at its root, and run:

git clone https://github.com/Demonbane18/astral-orchestrator.git
cd astral-orchestrator
sh scripts/setup.sh --dry-run
sh scripts/setup.sh

The dry run prints planned local changes. Setup registers the checkout, adds the plugin, and installs four companion profiles without overwriting a different file. A missing or customized profile does not weaken normal native routing: Codex can use the built-in native worker for Luna or Sol and the built-in native default for a reviewer with explicit values.

Setup cannot grant access to a model or effort your account does not have. Profile values take precedence when a matching profile is selected, so a mismatch blocks that lane.

First use

Start a new Codex task with Sol, Luna, or Astra at the effort you want for the primary, then say:

Use Astral Orchestrator to add a search box and verify every lane.

Orbit is the default, so you do not need to name it. For a different contract, explicitly name one of the other modes. For example:

Use Astral in Hypernova mode with the detected primary, configured workers, mandatory status, and exact-route checks.

Hypernova is never automatic. Morph is also user-owned: if you select an external provider, configure it separately and review its terms before sending a bounded worker packet.