Codex Astra Orchestrator + Luna Subagents
A configurable Codex setup where GPT-6 Astra is the root/orchestrator and reviewer, while GPT-5.6 Luna is the default and pinned model for execution subagents.
The installer asks which Codex plan you are on. Pro uses GPT-6 Astra at medium reasoning to orchestrate and GPT-5.6 Luna at max reasoning for execution subagents. Plus uses GPT-5.6 Luna at max reasoning to orchestrate and medium reasoning for execution subagents. Both plans retain the separate GPT-6 Astra reviewer at low reasoning.
Layout
.
├── .codex/
│ ├── config.toml (Pro: Astra root)
│ ├── config.plus.toml (Plus: Luna max root; installed as config.toml)
│ └── agents/
│ ├── explorer.toml
│ ├── worker.toml
│ ├── tester.toml
│ ├── reviewer.toml
│ └── researcher.toml
├── .agents/
│ └── skills/
│ └── astra-orchestrator/
│ └── SKILL.md
├── guides/
│ ├── fast-iteration.md
│ ├── complex-repo-work.md
│ ├── routine-coding.md
│ ├── full-orchestration.md
│ ├── plus-plan.md
│ └── token-usage.md
├── scripts/
│ └── token_usage.py
├── AGENTS.md
├── setup.sh
├── setup.ps1
└── LICENSE
Current Plus and Pro configuration
| Role or setting |
Plus |
Pro |
| Orchestrator |
GPT-5.6 Luna — max |
GPT-6 Astra — medium |
| Explorer, worker, tester, researcher |
GPT-5.6 Luna — medium |
GPT-5.6 Luna — max |
| Default subagent |
GPT-5.6 Luna — medium |
GPT-5.6 Luna — max |
| Independent reviewer |
GPT-6 Astra — low |
GPT-6 Astra — low |
| Concurrent subagent limit |
4 |
4 |
Pro — .codex/config.toml
model = "gpt-6-astra"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[agents]
enabled = true
max_concurrent_threads_per_session = 4
default_subagent_model = "gpt-5.6-luna"
default_subagent_reasoning_effort = "max"
Plus — .codex/config.plus.toml
model = "gpt-5.6-luna"
model_reasoning_effort = "max"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[agents]
enabled = true
max_concurrent_threads_per_session = 4
default_subagent_model = "gpt-5.6-luna"
default_subagent_reasoning_effort = "medium"
The installer writes whichever one matches your plan to .codex/config.toml
in the target repository; config.plus.toml itself is never installed.
Each role file is explicitly pinned to its intended model: Luna for explorer, worker, tester, and researcher; Astra for reviewer. This means changing only default_subagent_model will affect generic spawned agents, but not the named roles.
The four Luna role files omit model_reasoning_effort, so they use the selected plan's default_subagent_reasoning_effort unless the spawn request explicitly sets an effort. The reviewer keeps its explicit low effort. See the official subagent configuration documentation for precedence rules.
When updating an existing installation, update the four Luna role files along with config.toml; an older role file pinned to medium will override Pro's new max default.
If you want all named roles, including the reviewer, to follow the [agents] defaults, remove both the model and model_reasoning_effort overrides from their role files.
Project setup
Clone this repository:
git clone https://github.com/donvito/codex-astra-luna-orchestrator.git
cd codex-astra-luna-orchestrator
The target project must already exist and must be different from this setup
repository.
macOS and Linux
Run the shell installer:
./setup.sh
Windows
Run the PowerShell installer from Windows PowerShell:
powershell -ExecutionPolicy Bypass -File .\setup.ps1
With PowerShell 7, you can use:
pwsh -File .\setup.ps1
Installer prompts
When asked for the target repository, enter its absolute or relative path. For
example:
Target repository path: ../my-project
Next, choose your Codex plan:
Codex plan:
1) Pro - GPT-6 Astra orchestrates, GPT-5.6 Luna executes, GPT-6 Astra reviews
2) Plus - GPT-5.6 Luna (max reasoning) orchestrates, GPT-5.6 Luna executes, GPT-6 Astra reviews
Select plan [1/2] (default 1):
The selected configuration sets both the root and default subagent reasoning.
Agent role files are shared between plans: explorer, worker, tester, and
researcher use Luna at the plan's default effort; the reviewer uses Astra at low
effort on both plans.
The installer then asks whether to install each component:
.codex contains the root configuration and agent role profiles..agents contains the astra-orchestrator skill.AGENTS.md gives Codex the project-level orchestration instructions.
Press Enter or answer y to install a component; answer n to skip it. All
three components are selected by default.
If a component already exists, the installer lists the exact paths that would
be overwritten and asks again before making changes:
WARNING: the following existing files will be overwritten:
- .codex/config.toml
Update .codex? New files will be added; only paths listed above will be replaced. [y/N]
Existing-file updates default to n. If approved, missing files are added and
only the listed paths are replaced. Other files already present in the target
component remain untouched.
After setup, launch Codex from the target repository. Project-scoped .codex
configuration is loaded only for trusted projects.
See guides/ for copy-paste model presets and the Astra + Luna topology. The
guides are intentionally separate from the installers so you can review and
adapt settings for your Codex version without changing a global config
automatically.
Personal/global setup
For agents, copy the TOML files to:
~/.codex/agents/
For the skill, copy the skill folder to:
~/.agents/skills/astra-orchestrator/
Merge the settings from .codex/config.toml (Pro) or .codex/config.plus.toml
(Plus) into your existing:
~/.codex/config.toml
Do not blindly overwrite your existing global config if you already have MCP servers, providers, permissions, or other settings.
Using the skill
Codex may select the skill automatically when the task matches its description.
You can also invoke it explicitly from Codex CLI or the IDE extension with:
$astra-orchestrator
Example prompt:
$astra-orchestrator
Implement the new invoice export endpoint.
Have explorer map the existing invoice/export path first.
Use workers for bounded implementation, tester for verification,
and reviewer for an independent final review.
Suggested topology
GPT-6 Astra
root / orchestrator
|
+---------------+---------------+
| | |
explorer worker researcher
Luna Luna Luna
| |
+-------+-------+
|
tester
Luna
|
reviewer
Astra
|
v
GPT-6 Astra
integrate + verify
Tuning
For cheaper/faster runs:
- lower Pro's Astra reasoning from
medium to low
- set Luna reasoning to
low or medium
- use 3-4 concurrent threads
For larger codebases:
- consider raising Pro's Astra reasoning to
high
- start with your plan's Luna default and adjust based on results
- use 6-8 concurrent threads, only when tasks are actually independent
For strict parent/child separation:
- keep explorer/reviewer/researcher read-only
- keep worker/tester workspace-write
- leave the root in workspace-write so it can integrate changes
Token usage
Orchestration is not free: the root stays in the loop for the whole task and
every subagent carries its own context. Usage depends on repository size and
task shape, so there is no single number. scripts/token_usage.py reads the
rollout logs Codex already writes under ~/.codex/sessions and reports usage
per thread, role, and model, plus the change in your 5-hour and 7-day rate
limit windows:
scripts/token_usage.py --list --date 2026-09-07
scripts/token_usage.py --latest --date 2026-09-07
See guides/token-usage.md for a measurement
protocol, one sample run with real numbers, and tips for reducing usage.
Plus users: the root thread is the largest line item, so running it on Luna
saves the most. Selecting Plus in the installer does this for you; for a
manual or global setup see guides/plus-plan.md:
# Root
model = "gpt-5.6-luna"
model_reasoning_effort = "max"
Important behavior
Explicit model choices during a spawn override [agents] defaults. Custom agent files that specify model or model_reasoning_effort also take precedence over inherited defaults.
The execution role files are pinned to Luna intentionally, while the reviewer is pinned to Astra for independent final review. Astra remains the orchestrator unless you deliberately change the role configuration.
License
Licensed under the Apache License 2.0.
这是一套可配置的 Codex 设置：让 GPT-6 Astra 担任根编排器和独立审查者，而 GPT-5.6 Luna 作为执行子智能体（explorer、worker、tester、researcher）的默认固定模型运行。