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
Что это?Это конфигурируемая настройка Codex, при которой GPT-6 Astra становится корневым оркестратором и независимым ревьюером, а GPT-5.6 Luna работает как закреплённая модель по умолчанию для субагентов исполнения (explorer, worker, tester, researcher).
Это отдельное приложение или слой конфигурации для Codex?Само по себе это не приложение, а установщик, который записывает в существующий целевой репозиторий TOML-файлы конфигурации и профилей ролей в .codex, папку навыков .agents и файл AGENTS.md, настраивая мультиагентную оркестрацию OpenAI Codex CLI.
Как установить это в мой проект?Склонируйте этот репозиторий, затем из склонированной папки запустите shell-установщик на macOS/Linux или PowerShell-установщик на Windows, указав абсолютный или относительный путь к вашему существующему целевому репозиторию.
Нужен ли определённый тариф Codex, чтобы этим пользоваться?Да, установщик спрашивает, на каком вы тарифе — Codex Plus или Pro — и для каждого настраивает распределение моделей и уровней рассуждений по-своему: на Pro Astra работает на уровне рассуждений medium как оркестратор, а Luna — на max для исполнения; на Plus наоборот: Luna на max оркестрирует, а исполнение идёт на medium.
На что обратить внимание при обновлении или слиянии этой конфигурации?При обновлении существующей установки нужно обновить четыре файла ролей Luna вместе с config.toml, иначе старый закреплённый уровень effort перебьёт новое значение тарифа по умолчанию; а при глобальной настройке стоит сливать настройки вручную, а не перезаписывать существующую конфигурацию, если у вас уже настроены MCP-серверы или другие провайдеры.
Можно ли изменить, какая модель обслуживает каждую агентную роль?Да, каждый файл роли (explorer, worker, tester, researcher, reviewer) явно закрепляет свою модель, и можно удалить переопределения модели/рассуждений, чтобы роли возвращались к значениям по умолчанию из [agents].
Как отслеживать, сколько токенов расходует эта оркестрационная настройка?Входящий в комплект скрипт scripts/tokenusage.py читает rollout-логи, которые Codex пишет в ~/.codex/sessions, и показывает расход по ветке, роли и модели, включая изменения ваших окон лимитов на 5 часов и 7 дней.
Как вручную вызвать навык оркестрации?Codex может выбрать навык astra-orchestrator автоматически, когда задача совпадает с его описанием, либо вы можете вызвать его явно из Codex CLI или IDE-расширения.
Какой способ настройки предлагается для дешёвых запусков и для больших кодовых баз?Для более дешёвых/быстрых запусков снизьте уровень рассуждений Astra, опустите Luna до low/medium и используйте 3-4 параллельных потока; для больших кодовых баз поднимите рассуждения Astra ближе к high и используйте 6-8 параллельных потоков, только когда задачи действительно независимы.
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