Codex Astra Luna Orchestrator: a plan-aware Codex profile installer

What problem the Astra and Luna split is meant to solve

Most Codex setups use one model for everything. The README of codex-astra-luna-orchestrator argues for splitting the work: a stronger model plans and reviews, a cheaper or faster one executes. In the Pro profile, GPT-6 Astra runs at medium reasoning as the root orchestrator, GPT-5.6 Luna runs at max reasoning for execution subagents, and a separate GPT-6 Astra reviewer runs at low reasoning. The Plus profile inverts the orchestrator: GPT-5.6 Luna at max reasoning plans, Luna at medium reasoning executes, and Astra at low reasoning still reviews.

The target user is someone who has already decided to run Codex inside a repository and wants that role separation expressed as files rather than as a habit. The installer does not decide anything about your work. It copies a configuration that encodes a division of labour, and it asks which Codex plan you are on because the profiles differ by plan. That is the whole product.

How the profiles are laid out and why every role file is pinned

The repository keeps four profile directories: pro, plus, pro-max-2-subagents, and plus-max-2-subagents. Each one holds a codex/ directory with config.toml and agents/*.toml, plus an agents/ directory containing skills/astra-orchestrator/SKILL.md. The installer copies profiles/<plan>/codex to .codex and profiles/<plan>/agents to .agents in the target repository. The README states each profile is ready to copy, with no configuration rewriting during setup.

That last point matters more than it sounds. Because nothing is rewritten, what you read in the repository is what lands in your project. The cost is duplication: the same role files exist in several profiles, and the README warns that each role file is explicitly pinned to its intended model. Changing only default_subagent_model affects generic spawned agents but not the named explorer, worker, tester, and researcher roles. If you want every named role, including the reviewer, to follow the [agents] defaults, the README tells you to remove both the model and model_reasoning_effort overrides from those role files. So the pinning is deliberate, and it is also the first thing you will trip over when you want a different mix.

The concurrent subagent limit is the other axis. The standard Pro and Plus profiles set max_concurrent_threads_per_session = 4; the two max-2 variants set 2. That is a resource decision, not a quality one, and it is the only difference between the standard and max-2 profiles.

Installing it and running the first orchestrated task

The README requires the target project to already exist and to be different from the setup repository. Clone the setup repository first and change into it:

git clone https://github.com/donvito/codex-astra-luna-orchestrator.git
cd codex-astra-luna-orchestrator

On macOS and Linux, run the shell installer from that directory:

./setup.sh

On Windows, the README gives a PowerShell invocation that bypasses the execution policy for that one run:

powershell -ExecutionPolicy Bypass -File .\setup.ps1

The installer first asks for the target repository path. Enter an absolute or relative path to the project you want configured, for example ../my-project. It then prints a four-option menu and asks you to select a plan, with option 1, Pro, as the default. The menu text spells out what each choice means: Pro has Astra at medium orchestrating, Luna at max executing, Astra at low reviewing; Plus has Luna at max orchestrating, Luna at medium executing, Astra at low reviewing; options 3 and 4 are the same two configurations with a concurrent subagent limit of 2.

After the plan choice, the installer asks separately whether to install each of the three components: the codex directory as .codex, the agents directory as .agents, and AGENTS.md. Press Enter or answer y to install a component, n to skip it. All three are selected by default. If a file already exists, the installer lists the exact paths it would overwrite and asks again, and that second prompt defaults to n. Once approved, missing files are added and only the listed paths are replaced; other files already present in the target component are left alone.

When setup finishes, launch Codex from the target repository. The README notes that project-scoped .codex configuration is loaded only for trusted projects, so an untrusted project will not pick up the profile at all.

The overwrite prompt is the only real safety net

The installer is not transactional. It prints the paths it intends to replace and defaults to n, which is a sensible choice, but the safeguard stops there. There is no dry-run flag documented in the README, no backup of the replaced files, and no rollback command. If you approve the update and the new config.toml turns out to be wrong for your Codex version, the README does not describe how to undo it. You are expected to have version control in the target repository, which is a reasonable expectation for a Codex user and still an assumption the documentation never states.

The AGENTS.md handling is more careful than the rest. If the file already exists, setup appends the orchestration instructions and preserves the existing contents, and re-running setup skips the append when the same instructions are already present. Symbolic links and incompatible targets are skipped. That asymmetry is worth knowing: AGENTS.md is append-only and idempotent, while .codex and .agents are replace-in-place.

Where it is the wrong tool

This is a project-scoped installer. If you want one configuration for every repository on your machine, the README points at a separate manual path: copy the TOML files from profiles/<plan>/codex/agents/ into ~/.codex/agents/ and copy the skill directory into the equivalent global location. The installer itself does not do that for you.

The profiles also hard-code model identifiers such as gpt-6-astra and gpt-5.6-luna. If your account does not expose those models, or your Codex version names them differently, the copied configuration is not something the installer will fix. The README acknowledges this indirectly by keeping the guides separate from the installers, so you can review and adapt settings for your Codex version without changing a global config automatically. Adaptation is on you.

Finally, the whole design assumes your Codex build loads project-scoped .codex for trusted projects. If that is not how your build behaves, the orchestrator and subagent roles never activate and you are left with files that do nothing.

How it differs from a hand-written Codex config

The obvious alternative is writing .codex/config.toml and the role files yourself. The difference is not capability. A hand-written config can express the same model, model_reasoning_effort, approval_policy, sandbox_mode, and [agents] settings, and it can express combinations this repository does not ship, such as four concurrent subagents on the Plus profile with Astra executing.

What the repository adds is a fixed, reviewable set of presets and a plan-aware menu that maps a subscription tier to a reasoning-effort split. It also keeps the guides in guides/ separate from the installers, so the fast-iteration, complex-repo-work, routine-coding, full-orchestration, plus-plan, and token-usage documents can be read and adapted without the installer touching anything. If you enjoy tuning reasoning effort per role and already know what you want, the hand-written config is less indirection. If you would rather start from a working split and adjust two or three lines, the presets save that first pass.

Maintenance cost, licence, and what the repository does not cover

The last push was on 2026-09-16, the same day as the v0.1.0 release, so there is no upgrade history to reason about yet. The README's update procedure is manual: when updating an existing installation, copy the role files along with config.toml from the selected profile, replacing <plan> with pro or plus. There is no update script and no version marker in the copied files, which means after the first install you have to remember which profile you chose in order to update it correctly.

The licence is Apache-2.0, which permits commercial use and modification and requires that the licence and any notices be preserved. This is a description of the licence text, not legal advice; if you redistribute the profiles inside a product, read the LICENSE file and the Apache-2.0 terms yourself.

The repository also ships scripts/token_usage.py and a guides/token-usage.md document, but the README excerpt does not describe how the script is invoked or what it reads. Treat token accounting as something to inspect in the source before relying on it. The tests/ directory exists at the top level, and the README does not document what it covers, so the installer's behaviour on unusual target repositories is not something the documentation lets you predict.

Editorial conclusion

Adopt it if you already run Codex against a repository and want the orchestrator and subagent roles pinned to specific models and reasoning efforts without hand-editing TOML for every project. Skip it if you want a single global configuration, or if your Codex build does not load project-scoped .codex for trusted projects, because the whole design depends on that. Before installing, check that the target repository is separate from the setup clone, confirm which plan you are actually on, and read profiles/<plan>/codex/config.toml and the four Luna role files so you know exactly which paths setup.sh will overwrite.

Frequently asked questions

Official sources

1. donvito/codex-astra-luna-orchestrator on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases