codex-astra-luna-orchestrator README

The project's README from github.com/donvito/codex-astra-luna-orchestrator. As one markdown file: README.md.

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:

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:

For larger codebases:

For strict parent/child separation:

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-astra-luna-orchestrator (donvito/codex-astra-luna-orchestrator)

Searching Database…

1.7K ·GitHub
Codex-astra-luna-orchestrator
What is this?This is a configurable Codex setup that makes GPT-6 Astra the root orchestrator and independent reviewer while GPT-5.6 Luna runs as the default pinned model for execution subagents (explorer, worker, tester, researcher).
Is this a standalone app or a configuration layer for Codex?It is not an app itself, it is an installer that writes .codex config/role-profile TOML files, an .agents skill folder, and an AGENTS.md file into an existing target repository to configure OpenAI Codex CLI's multi-agent orchestration.
How do I install this into my project?Clone this repository, then from the cloned folder run the shell installer on macOS/Linux or the PowerShell installer on Windows, pointing it at the absolute or relative path of your existing target repository.
Do I need a specific Codex plan to use this?Yes, the installer asks whether you are on the Codex Plus or Pro plan and configures model/reasoning assignments differently for each: Pro puts Astra at medium reasoning as orchestrator with Luna at max for execution, Plus flips it so Luna at max orchestrates and runs execution at medium.
What should I watch out for when updating or merging this config?When updating an existing install you must refresh the four Luna role files along with config.toml or an old pinned effort will override the new plan default, and for a global setup you should merge settings manually rather than overwrite your existing config if you already have MCP servers or other providers set up.
Can I change which model handles each agent role?Yes, each role file (explorer, worker, tester, researcher, reviewer) explicitly pins its model, and you can remove the model/reasoning overrides to let roles fall back to the [agents] defaults instead.
How do I track how many tokens this orchestration setup is using?A bundled script, scripts/tokenusage.py, reads the rollout logs Codex writes under ~/.codex/sessions and reports usage per thread, role, and model, including changes to your 5-hour and 7-day rate limit windows.
How do I invoke the orchestration skill manually?Codex can select the astra-orchestrator skill automatically when a task matches its description, or you can invoke it explicitly from the Codex CLI or IDE extension.
What's the suggested way to tune this for cheap runs versus large codebases?For cheaper/faster runs, lower Astra's reasoning, drop Luna to low/medium, and use 3-4 concurrent threads; for larger codebases, raise Astra's reasoning toward high and use 6-8 concurrent threads only when tasks are truly independent.
What are similar projects?foreman, oh-my-subagents, openrig, jev-browser-use, Choir, symphony, ordewell, fractal
Which topics is it in?toml, openai-codex, config, token-usage, configuration, installer, gpt, orchestration, agent-orchestration, multi-agent, agents, coding-agent
Creator
donvito
Size
0.1 MB
Stars
1.7K
Updated
CommitOct 01Releasev0.2.2Oct 01
Age
1mo
Commits · 90 Days