GitHub - yeutterg/codex-orchestrator: Coordinate multiple repos from one OpenAI Codex orchestrator session.

6 min read Original article ↗

Coordinate cross-repo collaboration from one OpenAI Codex session.

This is for work that spans separate repos and needs one orchestrator session to understand dependencies, plan the work, and coordinate execution across them.

Typical cross-repo examples:

  • backend + device firmware + mobile app
  • backend + frontend + edge

In other words, this is not just "run Codex in one repo." It is for systems where multiple repos need to move together.

The workflow is:

  • each child repo runs its own codex app-server
  • the parent orchestrator connects to those child App Servers
  • the orchestrator deeply understands each repo and how the repos work together
  • the orchestrator writes plan.md
  • only then does the orchestrator delegate and track execution in runs.md

This repo is designed to work with the App Server functionality in Codex.

Model

flowchart TD
    O["Orchestrator<br/>plan.md<br/>runs.md"]

    subgraph Servers[" "]
        direction LR
        A[Child App Server A]
        B[Child App Server B]
        C[Child App Server C]
    end

    subgraph Repos[" "]
        direction LR
        RA[Child Repo A]
        RB[Child Repo B]
        RC[Child Repo C]
    end

    classDef invisible fill:transparent,stroke:transparent,color:transparent
    class Servers,Repos invisible
    O <--> A
    O <--> B
    O <--> C
    A --> RA
    B --> RB
    C --> RC
Loading

The user talks only to the orchestrator.

Benefits

  • One place for the user to interact, instead of coordinating multiple child sessions manually.
  • Better for multi-repo changes because the orchestrator can understand dependencies and plan across repos before execution.
  • More durable than chat-only workflows because plan.md and runs.md survive compacting and restarts.
  • Easier to manage human checkpoints because testing, approvals, and clarification all route through the orchestrator.
  • Keeps each repo in its own real working context instead of forcing everything into one repo or one flattened session.

Limitations

  • This pattern currently only works with Codex, because it depends on Codex App Server behavior and Codex skill execution.
  • This pattern is designed around App Server. Sharing a Codex session as an MCP server does not expose enough useful information to the orchestrator for this workflow.
  • After you run codex app-server in each child repo, that terminal mostly just hosts the server process. It does not give you a useful live view of the child run.
  • In practice, execution visibility lives in the orchestrator session and in runs.md, not in the child App Server terminals.

Install

Install the skill:

mkdir -p "$HOME/.codex/skills"
cp -R /absolute/path/to/codex-orchestrator/skills/codex-orchestrator "$HOME/.codex/skills/"

Then invoke:

Workflow

1. Start Each Child App Server

In a separate terminal for each child repo:

cd /absolute/path/to/child-1
pwd
codex app-server
cd /absolute/path/to/child-2
pwd
codex app-server
cd /absolute/path/to/child-3
pwd
codex app-server

Copy the pwd output for each repo. You will paste those paths into the orchestrator. Use plain codex app-server by default.

2. Start The Orchestrator

In the orchestrator repo:

cd /absolute/path/to/codex-orchestrator
pwd
codex

If you want to run the orchestrator in YOLO mode, this is the place to do it:

cd /absolute/path/to/codex-orchestrator
pwd
codex --dangerously-bypass-approvals-and-sandbox

Use that only if you intentionally want the orchestrator to run with maximum autonomy. In most cases, child App Servers should still stay on plain codex app-server.

Then invoke:

Best case, you give the orchestrator everything it needs in one kickoff prompt:

  • the problem to solve
  • the pasted absolute working directory for each child repo
  • any optional logging, instrumentation, or pre-execution test requests

Example kickoff prompt:

Use $codex-orchestrator.
The problem is: <describe the problem>.
The child repo directories are:
- child-1=<paste pwd>
- child-2=<paste pwd>
- child-3=<paste pwd>

From there, it should proceed mostly autonomously. It should only ask you for more input when a step genuinely requires human action or human judgment.

3. What Happens Next

The orchestrator will:

  • understand code, git state, commit history, and docs in each repo
  • understand how the repos work together
  • write plan.md
  • execute only after the plan exists
  • keep runs.md updated as it learns more

If the user asked for extra logging, instrumentation, or test runs, the orchestrator should include that in plan.md.

If a child needs testing, approval, credentials, or clarification, the orchestrator should stop there and ask the user with exact steps and the exact result it needs back.

End-To-End Examples

Example 1: Backend, Device, And Mobile App

Example: backend, device firmware, and a mobile app repo all need coordinated work for a new device onboarding flow.

  1. Start each child repo like this and copy each repo path with pwd:
cd /absolute/path/to/child-repo-0
pwd
codex app-server
cd /absolute/path/to/child-repo-1
pwd
codex app-server
cd /absolute/path/to/child-repo-2
pwd
codex app-server
  1. Start Codex in the orchestrator repo and invoke $codex-orchestrator.
  2. Give the orchestrator one kickoff prompt with the problem statement and the pasted repo paths.
  3. The orchestrator will understand each child repo, identify the cross-repo contracts, and write plan.md.
  4. Only then will it delegate execution to the child repos and keep runs.md updated. It should only come back to you when it actually needs input.

Example prompt:

Use $codex-orchestrator.
The problem is: when the mobile app tries to connect a new device, it
shows "Connecting..." for about 30 seconds and then fails with
"device registration timed out", even though the backend eventually creates
the device record and the microcontroller firmware appears online a few
seconds later.
The child repo directories are:
- mobile=<paste pwd from child-repo-0>
- backend=<paste pwd from child-repo-1>
- firmware=<paste pwd from child-repo-2>

Example 2: Backend, Frontend, And Edge

Example: backend, frontend, and edge all need coordinated work for a request flow that crosses browser UI, API behavior, and edge execution.

Example prompt:

Use $codex-orchestrator.
The problem is: users can submit a checkout form in the frontend, but the
edge function intermittently drops the session header before the request
reaches the backend, so the UI shows a generic 500 error instead of the
expected validation response.
The child repo directories are:
- frontend=<paste pwd from child-repo-0>
- backend=<paste pwd from child-repo-1>
- edge=<paste pwd from child-repo-2>

Files

  • plan.template.md: template for the live plan.md
  • runs.template.md: template for the live runs.md
  • skills/codex-orchestrator/: the skill

Generated working files such as plan.md, runs.md, and orchestrator.config.yaml are intentionally gitignored.

Contributing

Contribute reusable improvements to the skill, templates, and docs. Do not commit generated local state such as plan.md, runs.md, orchestrator.config.yaml, or .orchestrator/.