Orchestrator Mode

Orchestrator Mode is how MadoAgent hands off a self-contained task to a Codex worker without you babysitting a terminal. Instead of opening an interactive Codex session and watching it type, MadoAgent launches a headless, non-interactive Codex run in its own tile. The worker either finishes on its own or the sandbox rejects the action — it never stops to ask you a question, so there is nothing to babysit.

It is the right shape for fire-and-forget work dispatched from MadoAgent: "refactor this module", "write the migration for this table", "generate tests for this file". You ask, the worker runs, you check back when it is done.

A tile created by Orchestrator Mode carries a Worker badge in its title bar, so a headless worker is visually distinguishable at a glance from a terminal you opened by hand. The badge survives an app reload.

What you can do with it

• Dispatch a headless Codex worker from MadoAgent for a task that does not need your input mid-run.
• Pick a sandbox mode to control what the worker is allowed to touch:

  Mode	What the worker can do
  read-only	Read files, but not modify them or run side-effecting commands.
  workspace-write (default)	Read and write inside the working directory.
  danger-full-access	No sandbox restrictions. Must be chosen explicitly — MadoAgent never selects this on its own.

• Let MadoAgent supervise progress — it watches the worker tile and reports back when the run is done, failed, or still running.
• Cancel a derailed worker if MadoAgent judges the run looks off-track.

How to use it

1. Open MadoAgent with Cmd+Shift+M (⌘⇧M).
2. Ask for a dispatched worker, for example "dispatch a Codex worker to refactor auth.ts into a class".
3. MadoAgent opens a new terminal tile with a Worker badge and launches the headless Codex run inside it.
4. MadoAgent polls the tile and tells you when the worker is done, failed, or still running. You can also click the tile yourself to read its output at any time.

The default sandbox is workspace-write specifically so a dispatched worker cannot touch anything outside the project directory without an explicit, deliberate choice to loosen it.

Common use cases

• "Dispatch a Codex worker to write the migration for the new users table." Fire it off, keep working, check the tile when MadoAgent reports it done.
• "Run a read-only Codex worker to summarize what payments/ does." Use the read-only sandbox so the worker can look but not change anything.
• "Generate tests for auth.ts in a worker while I keep coding here." The Worker badge keeps the headless run visually separate from your interactive terminals.

Tips and best practices

• Use read-only for analysis tasks (summarize, explain, audit) — there is no reason to grant write access when nothing should change.
• Stay on workspace-write for normal refactors. Only reach for danger-full-access when a task genuinely needs to reach outside the project directory, and pick it deliberately.
• If MadoAgent reports a worker as "still running" but it looks derailed, ask MadoAgent to cancel it rather than waiting it out.
• Treat the worker tile as the source of truth for what happened — MadoAgent's summary is a convenience, the tile has the full output.

Related features

• MadoAgent — the panel you dispatch workers from.
• Agent Routing — how MadoAgent decides what to send where.
• Ensemble Exploration — for when you want several workers on the same problem instead of one.

Limitations

• Workers run with approvals turned off — anything the sandbox does not allow is auto-rejected rather than blocking on a prompt nobody will answer. Plan your sandbox mode accordingly.
• A headless worker is not interactive. If a task needs you to answer permission prompts mid-run, use an interactive Codex tile instead.
• Workers run on your local Codex CLI; you need Codex configured for them to start at all.