Orchestrator README

Orchestrator MCP

one agent. second opinion. same terminal.

Make Claude Code ask Codex. Make Codex ask Claude Code.
Use the subscriptions already signed in on your computer.
No provider API keys to configure.

See it · Compare · Install · What you get · Reviews · Workflow · Security · Dashboard

Orchestrator MCP is a local Model Context Protocol server that lets one coding agent consult another. It launches the Codex, Claude Code, OpenCode, GitHub Copilot, or experimental Antigravity CLI already installed and authenticated on your machine, routes the request, and returns a structured answer.

It does not ask for a provider key, proxy provider traffic, or silently switch models. Authentication remains inside each vendor's CLI.

Quick start from Claude Code, with Codex already logged in (other hosts: Install):

uv tool install orchestrator-mcp-server              # or pipx, pip, or brew
orchestrator-mcp-server init --host claude           # writes ~/.orchestrator-mcp/config.yaml
claude mcp add orchestrator \
  --env ORCHESTRATOR_CONFIG=$HOME/.orchestrator-mcp/config.yaml \
  --env ORCHESTRATOR_HOST_RUNTIME=claude -- orchestrator-mcp-server

Then ask Claude Code for a second opinion from Codex.

Before / After

Same subscriptions. Less context shuffling.

 Claude Code host  ──►  Orchestrator MCP  ──►  Codex CLI
 Codex host        ──►  Orchestrator MCP  ──►  Claude Code CLI
 Any host          ──►  Orchestrator MCP  ──►  OpenCode CLI (DeepSeek, Qwen, Kimi…)
 Any host          ──►  Orchestrator MCP  ──►  GitHub Copilot CLI
 Any host          ──►  Orchestrator MCP  ──►  Antigravity CLI (experimental)

                         local routing
                    no provider API keys
                no same-execution-identity loops

Ordinary orchestrator_consult calls exclude the host's entire runtime: Claude Code cannot use that tool to consult Claude Code, and Codex cannot use it to consult Codex. Reviews and workflows use the narrower (runtime, model) execution identity; when consult.host.model names the host precisely, they may route to a provably different, versioned model on the same runtime. The host can never route work back to its own execution identity.

How it compares

If Claude Code asking Codex is all you need, OpenAI's codex-plugin-cc does that, with background jobs. PAL MCP reaches many models through provider API keys. Orchestrator is for the rest:

Calls block the turn that makes them, often for minutes. To keep working meanwhile in Claude Code, have a background subagent make the call.

Google's Gemini CLI stopped serving free and Google AI Pro/Ultra accounts on June 18, 2026; Google models are reached here through its successor, Antigravity CLI.

Install

Claude Code: install as a plugin. Needs uv on your PATH, and at least one of Codex, Antigravity, OpenCode or GitHub Copilot installed and logged in (step 1 below). What you consult them about — prompts, diffs, file contents — goes to those providers under your own logins, and the usage is billed to your accounts with them; see the privacy policy and the Security model. In Claude Code:

/plugin marketplace add crAK1644/orchestrator-mcp
/plugin install orchestrator-mcp@orchestrator-mcp
/orchestrator-mcp:setup

/orchestrator-mcp:setup writes ~/.orchestrator-mcp/config.yaml from the agent CLIs it finds, then runs doctor on it. It finds Codex, Antigravity and GitHub Copilot; OpenCode goes into the config by hand, from its agent in config.example.yaml. Then reconnect plugin:orchestrator-mcp:orchestrator in /mcp, or restart Claude Code: /reload-plugins keeps the server that started without a config.

If you added the server earlier with claude mcp add orchestrator, remove that entry (claude mcp remove orchestrator -s <scope>, with the scope claude mcp get orchestrator shows), or two copies of the server run side by side.

Every other host, and Claude Code without the plugin, installs the server itself:

Homebrew:

brew tap crAK1644/tap
brew install orchestrator-mcp-server

Apple Silicon uses a prebuilt package. Intel macOS and Linux build dependencies from source; use the uvx option if you want a faster, temporary install.

uv, pipx or pip: uv tool install orchestrator-mcp-server, pipx install orchestrator-mcp-server, or pip install orchestrator-mcp-server into a virtualenv. Python 3.11 or newer.

1. Sign in to the agent CLIs

Sign in to each agent you want Orchestrator to use:

codex login
claude auth login

These are the normal Codex and Claude Code login flows. Orchestrator checks readiness, but never reads or stores their credentials.

For OpenCode, sign in once with opencode auth login for whichever provider you plan to consult. Hosted providers only — this server does not run a model on your machine. See the OpenCode runtime section below.

For GitHub Copilot, sign in to the copy of its state that Orchestrator runs it under, not to your own: COPILOT_HOME=$HOME/.orchestrator-mcp/copilot/home copilot login. init prints that command when it writes a Copilot agent, and a consultation that finds it signed out returns it in required_action. It needs a Copilot plan; see the GitHub Copilot runtime section below.

2. Write a starter config

orchestrator-mcp-server init --host claude   # or codex: the client you run it under

init finds the Codex, Claude Code, GitHub Copilot and Antigravity CLIs installed here, writes ~/.orchestrator-mcp/config.yaml (mode 0600, never over an existing file; --path picks another), and prints the exact line for step 3. It picks the best reviewer that is not the host. Copilot is scored below the others, so it is the reviewer only when it is the only CLI beside the host, and it comes last under deep_reviewers. Its agent is written on model: auto, the one model every plan serves, so the name cannot go stale, and init prints the sign-in command from step 1. It writes no workflow: block, because only you can choose the directories a workflow may work in, and no OpenCode agent, because its model names change too often for a template; add one by hand from config.example.yaml.

consult:
  database_path: ~/.orchestrator-mcp/consultations.sqlite3
  timeout_s: 180

  agents:
    codex:
      runtime: codex
      command: codex
      model: gpt-5.6-sol
      priority: 10
      web_search: true
      scores: { coding: 95, research: 90, reasoning: 95, review: 90 }

    claude:
      runtime: claude
      command: claude
      model: claude-opus-5-5
      priority: 10
      web_search: true
      scores: { coding: 90, research: 95, writing: 95, review: 95 }

3. Add the server to your MCP client

init printed this with your paths filled in.

claude mcp add orchestrator \
  --env ORCHESTRATOR_CONFIG=$HOME/.orchestrator-mcp/config.yaml \
  --env ORCHESTRATOR_HOST_RUNTIME=claude \
  -- orchestrator-mcp-server

[mcp_servers.orchestrator]
command = "orchestrator-mcp-server"
env = { ORCHESTRATOR_CONFIG = "~/.orchestrator-mcp/config.yaml", ORCHESTRATOR_HOST_RUNTIME = "codex" }

{
  "mcpServers": {
    "orchestrator": {
      "command": "/opt/homebrew/bin/orchestrator-mcp-server",
      "env": {
        "ORCHESTRATOR_CONFIG": "~/.orchestrator-mcp/config.yaml",
        "ORCHESTRATOR_HOST_RUNTIME": "claude"
      }
    }
  }
}

{
  "servers": {
    "orchestrator": {
      "type": "stdio",
      "command": "orchestrator-mcp-server",
      "env": {
        "ORCHESTRATOR_CONFIG": "~/.orchestrator-mcp/config.yaml",
        "ORCHESTRATOR_HOST_RUNTIME": "claude"
      }
    }
  }
}

{
  "mcp": {
    "orchestrator": {
      "type": "local",
      "command": ["orchestrator-mcp-server"],
      "environment": {
        "ORCHESTRATOR_CONFIG": "~/.orchestrator-mcp/config.yaml",
        "ORCHESTRATOR_HOST_RUNTIME": "opencode"
      }
    }
  }
}

Restart the MCP client after changing its configuration.

[!TIP] Give ORCHESTRATOR_CONFIG an absolute path or one under ~. GUI-launched clients often start in a different working directory and inherit a smaller PATH than your terminal.

4. Check it

ORCHESTRATOR_CONFIG=~/.orchestrator-mcp/config.yaml ORCHESTRATOR_HOST_RUNTIME=claude \
  orchestrator-mcp-server doctor

One ok or FAIL line per check: the config loads, the database opens, and each agent's CLI is installed and logged in. It exits 1 if anything failed. The only things it runs are the CLIs' own login checks, so no project material leaves the machine.

The client spawns the server and talks to it over stdin, so orchestrator-mcp-server is not a command you start yourself. (The dashboard is the other half of this distribution and is started by hand.) Two flags answer questions from outside a client, besides init and doctor above:

orchestrator-mcp-server --version   # which build the client will spawn
orchestrator-mcp-server --help      # what the environment variables have to say

Both answer and exit without reading your configuration. Anything else on the command line, besides the reports below, is refused rather than ignored. To make the server read the configuration, run it with no arguments: a file it cannot accept leaves as a message naming the key -- one line for most mistakes, several for a schema violation, never a traceback.

Reports from the terminal

Six read-only commands print what the database already holds. They run instead of the server, read the same config for its database_path, and open the file read-only: they never migrate it, so a database from an older version gets a sentence telling you to start the server once.

orchestrator-mcp-server usage [--days 30] [--json]      # turns, tokens and cost per agent and model
orchestrator-mcp-server history [--limit 20] [--kind review] [--json]   # recent records, with their ids
orchestrator-mcp-server scorecard [--days 30] [--json]  # how each reviewer answered, and what became of its findings
orchestrator-mcp-server strengths [--days 30] [--json]  # how each agent answered each kind of question, how fast, at what cost
orchestrator-mcp-server search WORD... [--days N] [--limit 10] [--json]   # stored prompts and answers that hold every word
orchestrator-mcp-server export ID                       # one record and everything it owns, as JSON

A price is shown only when every turn in the group reported one; otherwise it reads unknown beside the sum of the prices that were reported, never as zero. The scorecard counts a finding as kept when the host marked it fixed or accepted_risk and rejected when it marked it rejected; those are dispositions the host reported when it finalized a review, which this server does not check, and a later recheck does not update them. A reviewer's hit rate appears once ten findings are decided. Recheck reviews are left out so the same finding is not counted twice, and a review with no synthesis on record (not finalized yet, or store_full_content: false, under which finalizing is refused) is counted as asked but not judged.

sole serious counts the critical and important findings that only that reviewer raised, in reviews where at least two reviewers answered, and that the host did not reject. Open ones count too, since a recorded fix round does not change a disposition. It is what a second reviewer would have missed. A reviewer that never answered beside another shows -.

strengths answers "who is good at what?". Per kind of question (coding, research, review and so on), agent and model it counts the turns asked, answered and failed, the average time an answer took, and the cost. Every consultation counts, a reviewer's and a workflow step's included; a turn that never started, or that the spend ceiling stopped, does not. A failure rate appears from five asks, and a review row also carries the scorecard's hit rate. Under the table, lines name what may be worth a look and change nothing: an agent that failed at least 30% of five or more asks for a kind of question, with its commonest error (a setup error such as connection_required is called setup and points at doctor); and a kind of question that your config routes to an agent which took at least twice as long per answer as another configured agent that failed no more often, five answers each, on the models configured today. An agent or model the config no longer holds is never suggested. The routing is worked out as the server would, leaving out the host's own runtime when ORCHESTRATOR_HOST_RUNTIME names one. None of this says whose answers were better: only review rows carry a signal of that, and agents were not asked the same questions.

search answers "which agent told me that?". A stored prompt or answer matches when it holds every word, best match first, and a word also matches its other endings (search finds searched). Each hit shows a short excerpt with the matching words in «marks», the agent and model, the date, and the id to export. A reviewer's hit names its review. Words are only words: AND, NEAR, *, : and quotes mean nothing special, and a query is at most 200 characters. --limit is at most 25 and --days defaults to all of it. The index is built in memory for each call from the text as it would be printed, so a credential in an old row can be neither read nor searched for, and nothing is added to the database. That costs about a fifth of a second for each megabyte of stored text. It finds nothing when store_full_content is false, which keeps no text, and says so. The same search is the read-only tool orchestrator_search_consultations.

export takes a full id or a unique prefix of at least eight characters from history. It prints the record as stored, run through the same masking as everything else, without session ids or confirm-token hashes; a review or workflow names the consultations it owns by id, and you export those to read them. What it prints is your prompts and the answers, so treat it as you would the database. Opening a WAL database read-only can create -wal and -shm files beside it; the database file itself is never written.

Run with uvx instead

claude mcp add orchestrator \
  --env ORCHESTRATOR_CONFIG=$HOME/.orchestrator-mcp/config.yaml \
  --env ORCHESTRATOR_HOST_RUNTIME=claude \
  -- uvx orchestrator-mcp-server

[mcp_servers.orchestrator]
command = "uvx"
args = ["orchestrator-mcp-server"]
env = { ORCHESTRATOR_CONFIG = "~/.orchestrator-mcp/config.yaml", ORCHESTRATOR_HOST_RUNTIME = "codex" }

What you get

The consultation tools

These deletion tools remove local SQLite records only. They cannot erase a consulted runtime's own CLI or provider history.

Three independent opt-ins: the consult tools are always advertised, the review tools only with a consult.review block, the workflow tools only with a consult.workflow block. Reviewers are not a workflow, and a workflow is not reviewers.

Slash commands

The server also serves MCP prompts, which a client that speaks prompts/list renders as slash commands. In Claude Code they appear as /mcp__<server-name>__<command>, where the server name is whatever you called it in your MCP client config — /mcp__orchestrator__review for the orchestrator entry shown above. Installed as the plugin, the server is named plugin_orchestrator-mcp_orchestrator, so the same command is /mcp__plugin_orchestrator-mcp_orchestrator__review.

Every argument is optional; a command with none expands into an instruction to ask you for the missing part. A client that speaks completion/complete offers the configured agents for agent and recent ids for workflow_id. review and workflow are advertised only when their tools are, on the same two answers — a command that could only reply "no reviewers are configured" costs a round trip and reads like a bug.

Two things worth being clear about. Nothing is installed. These arrive over the same stdio connection as the tools: no command directory, no generated markdown, nothing written to your machine, and a client that does not speak prompts/list is unaffected. A prompt is text, not an action. Expanding one consults nobody, sends nothing, and starts no workflow — it reaches the host's conversation as if you had typed it, and the host then calls the tools, checkpoints and all. They exist because the flows worth having here are handshakes, and a host driving them from tool descriptions alone tends to skip the checkpoint that makes them worth having.

Resources

Each record is also a resource template, for a client that attaches resources rather than calling tools: orchestrator://consultation/{consultation_id}, orchestrator://review/{review_id} and orchestrator://workflow/{workflow_id} read as the JSON the matching get tool returns, and the id completes from recent history. Templates list no instances; the list tools are how you find an id. Each is advertised on the same opt-in as its tools.

The review and workflow view

In a host that renders MCP Apps, such as Claude Desktop, orchestrator_get_review, orchestrator_finalize_review and orchestrator_workflow_status show their result as a table: findings by severity, reviewer and location, or a workflow's steps and what can run next. The page ships in the package as ui://orchestrator/view.html, loads nothing from the network, and puts reviewer text on the page as text, never as markup. Other hosts get the same text result as before.

How consultation works

orchestrator_consult selects the eligible agent with the highest capability score. Lower priority wins a score tie; agent ID breaks the final tie. Set consult.score_margin to let priority decide among agents within that many points of the top score: give a cheap or free agent a low priority and a margin of 5, and its 92 beats a paid agent's 95. The default 0 keeps the plain score order. A missing capability or a score of 0 makes an agent ineligible.

The selected CLI runs under its existing login and returns one response envelope:

If the chosen agent fails, Orchestrator returns that failure. It does not quietly fall through to a different model.

Choose the evidence source

Reviews, with a checkpoint

A consultation asks one agent. A review asks one or more configured reviewers the same question over the same material.

 plan review          approve + run          synthesize
 sends nothing   ──►  reviewers answer  ──►  host records conclusion
      │                    in parallel                │
      └─ scope              one-time token            └─ every Critical and Important kept
         reviewers
         secret hits
         request count

Enable reviews in config.yaml:

consult:
  review:
    reviewers: [codex]          # standard: exactly one
    deep_reviewers: [codex, claude]  # deep: one to five
    roots: [~/src]              # context_paths and diff_ref are restricted to these trees
    checklist:                  # optional: added to every reviewer's instructions
      - a fix that patches the reported line but not the same mistake beside it
    escalate:                   # optional: paths that deserve a deep review
      - src/auth/*

checklist is for the mistakes your reviews keep finding. Each entry goes to every reviewer under "Check especially for:"; leave it out and the instructions are unchanged.

escalate names the paths where a standard review is not enough. When a standard review's diff_ref touches one, the plan carries escalate: {paths, suggestion: "mode=deep"}. It only suggests: the reviewers stay as planned, and re-planning as deep is the host's call. The globs are fnmatch patterns over repository-relative paths, so * also crosses /. A name git quotes in a diff (one holding a tab, a double quote, or non-ASCII characters while core.quotePath is on) is never matched.

For a branch review, skip the file: diff_ref lets Orchestrator run the diff itself.

orchestrator_review(goal="...", diff_ref="main...HEAD", diff_repo="~/src/myproject")

A..B diffs the two commits, A...B diffs from their merge base (what a pull request shows), and a single commit X is X^..X (a merge means its first parent). diff_repo may be left out when roots names exactly one directory. diff_ref cannot be combined with context or context_paths.

• Both ends are resolved to commit SHAs before the diff runs, and the plan's manifest shows them. Moving the branch between the plan and the run changes the approval hash, so the token no longer fits.
• Only committed changes. The working tree and the index are not read; commit first or pass the diff through context.
• The repository, and the top level of the repository it sits in, must both be beneath roots. Pointing diff_repo at a subdirectory of a repository outside them is refused. So is a checkout whose git data lives elsewhere: a linked worktree of a repository outside roots, a .git file pointing out, or objects/info/alternates (a git clone --shared) naming a directory outside.
• git runs with external diff programs, textconv filters, replacement refs and lazy fetching off, so a repository whose config names a program cannot make this run it. In a partial clone a diff that needs a missing blob fails instead of fetching it. Binary files appear as "differ", not as bytes.
• A manifest you pass as material is kept, listed after the pinned endpoints, and leaves material_verified false.
• One limit: git opens the directory by name after the check, so someone who can already write inside a root and swap the repository for a symlink in that instant can redirect it. Closing that needs an OS sandbox around git.
• The reviewer receives the diff, whose headers carry file paths relative to the repository, never the repository's own location.

context_paths is a convenience for material too large to paste into a tool argument. Orchestrator reads each named file beneath those roots and sends its contents to the reviewers. The path string supplied by the caller is also included as the file heading and manifest label, so an absolute path can disclose a username or directory layout. If that is sensitive, pass the bytes through context with neutral labels instead.

Each root has to be an absolute path to a directory that exists. The server checks that at startup and refuses to start naming the one it could not find, rather than starting and failing the first context_paths call -- which is a reviewer's turn later.

The workflow is deliberately split:

1. orchestrator_review creates a plan and sends nothing. The plan shows reviewers, material size, web access, request count, and locations of credential-shaped text. suspect_hits adds the lines holding a long random-looking token that no pattern names (32 characters of letters and digits, say). It is a guess: hex, UUIDs, integrity hashes, names in snake_case or kebab-case, and a name of letters alone with a number on the end (LoaderV2) are left alone, and so is a line already in secret_hits. It never blocks and is not stored. A key of letters alone, or of hex, gets past it, so read the material yourself. A plan nobody runs within a day is dropped the next time a review is planned.
2. Show that plan to the user. orchestrator_review_run spends its one-time token and asks reviewers in parallel.
3. Read every result and call orchestrator_finalize_review. Reviewer replies alone leave the review at awaiting_synthesis.

The checkpoint binds the scope and makes the token single-use, but it is advisory: MCP gives the server no separate human channel, so it cannot prove who saw the plan. Human approval depends on the calling client's tool-confirmation experience or an external gate.

Finalization must preserve every machine-readable Critical and Important finding, even when other reviewers disagree with it. Deep mode also requires the host agent to record its own findings before seeing the reviewers' answers.

[!IMPORTANT] Material sent to a reviewer may remain in that vendor CLI's own history. Orchestrator cannot erase Codex, Claude Code, OpenCode, GitHub Copilot, or Antigravity session logs.

The three-phase workflow

A consultation is one question. A review is one body of material. A workflow is a whole job held together: research and planning, implementation and testing, review and fixing, with failed tests and open serious findings feeding a capped fix loop. Every consultation and review it produces hangs off one workflow_id.

 research? → plan → author_execution_prompt → implement
                                               └→ [apply_patch if delegated] → test

 test
 ├─ failed by default → fix → [apply_patch if delegated] → test
 └─ passed / advance_on_failed_test → review → synthesize

 synthesize
 ├─ clean → completed
 └─ open serious findings → fix

 `?` means research may be skipped. Fixing is capped at `max_fix_rounds`.

Enable it in config.yaml. Without a workflow: block the workflow tools are not advertised at all, the same rule the review tools follow:

consult:
  host:
    runtime: claude              # asserted against ORCHESTRATOR_HOST_RUNTIME
    model: claude-opus-5         # optional; see "Host identity" below
  workflow:
    max_fix_rounds: 5
    roots: [~/src]
    advance_on_failed_test: false
    review_policy:
      different_from_implementer: true
      different_from_planner: false
    bindings:
      research:  {agent: codex-sol}
      plan:      {agent: codex-sol}
      author_execution_prompt: {executor: host}
      implement: {agent: nemotron-ultra, execution: patch}
      apply_patch: {executor: host}
      test:      {executor: host}
      review:    {agents: [codex-sol, claude-opus]}
      synthesize: {executor: host}
      fix:       {agent: codex-sol, execution: patch}

workflow: requires store_full_content: true and refuses at startup otherwise. A workflow is its stored plans, briefs, patches and reports, and the review step cannot finalize without them — the failure belongs at boot, not several paid steps in.

roots: follows the same rule as review.roots: — absolute after ~/$VAR expansion, and a directory that exists, checked at startup. A relative root is refused rather than resolved against wherever the client spawned the server, which would make the allowlist something other than what the file says.

Models are not tied to phases

A binding is one of three shapes, and mixing them is a startup error:

Leaving agent: out means auto: routed by capability score for the step, ties broken by priority then agent id, the same rule orchestrator_consult uses. GPT, Claude, DeepSeek, Gemini, Qwen — any model reachable through a supported runtime can take any step it scores for and is permitted the mode for. A step with no binding falls to the host, which is the conservative default — with one exception. review cannot be the host's: its product is a review row that only the review service writes, and a host-recorded outcome would be a synthesis written straight into a step. Because unbound steps default to the host, a config that simply never mentions review is refused at workflow_start, before anything has been spent, rather than at the review step after research, planning and implementation have all been paid for.

Steps route on the four capabilities added for this: planning, prompt_authoring, testing and synthesis, alongside coding, research and review.

Bindings are resolved and snapshotted at workflow creation, and so is the policy they run under — the round cap, advance_on_failed_test and the review policy. Editing config.yaml does not reroute a running workflow or move its cap; that takes orchestrator_workflow_plan_replan and its own approval. A replan re-decides the steps you name and leaves every other one on the routing the workflow already had.

Presets

A preset is a named set of bindings for the steps you would rather not spell out at every start. workflow_start(preset="cheap") layers it over the rest, lowest to highest: the host default, bindings:, the preset, then the bindings argument of that call. A preset names only the steps it changes.

    presets:
      cheap:
        research: {agent: flash}
        plan:     {agent: flash}

A preset is checked when the config loads, exactly as bindings: is: an unknown agent, a mode the step does not take, or a mix of shapes refuses the boot and names workflow.presets.<name>.<step>. A name is lowercase, [a-z][a-z0-9_-]{0,31}. An unknown preset at start is refused and the configured names are listed. The preset name is not stored: what a workflow runs under is the resolved snapshot, so editing a preset later does not move a running workflow.

Execution modes, and what each one can reach

execution_modes on an agent is operator trust, not capability. What actually happens is the intersection of that list with what the runtime can be made to do, and a refusal names which side said no.

A root allowlist and a prompt instruction are not containment. An agent that declares isolated_write on a runtime that cannot be contained is refused at startup, not at routing time.

No delegated agent writes to your working tree. In patch mode the agent never sees your checkout — only the context the host sent it, exactly as a reviewer does — and the diff comes back for the host to apply. In isolated_write it sees a copy: a worktree under ~/.orchestrator-mcp/worktrees/<workflow_id>/<step_id>/, checked out at the latest applied result (the workflow's baseline until the host has applied anything). It is normally deleted after the diff is captured and its private recovery copy is written. It is retained when capture fails or recovery cannot safely preserve the patch, because the worktree may then hold the only usable copy. Either way the successful step ends in awaiting_host_apply and the host owns the branch. ConsultAdapter gained nothing for any of this: it is still three verbs with no way to ask for anything agentic, and write capability lives in a separate package behind a separate protocol.

Four things about a contained run are worth knowing before you use one:

• The diff is the record, not the reply. Orchestrator runs git add -A in the worktree and takes the staged diff against the baseline, so files the agent created are captured too — a plain git diff <baseline>.. would miss them. The model's summary is stored beside the patch as a description of its work, never as the account of it. Its list of commands is stored the same way, and is knowingly incomplete: codex omits sandbox-denied commands from its event stream entirely.
• The agent cannot commit. A worktree's git directory lives outside its sandbox, so git add, commit, stash and checkout all fail from inside. It leaves the work in the tree and this server records it. The step's timeout is consult.workflow.execution_timeout_s (900s by default), not consult.timeout_s, which is sized for a question.
• Two things a diff cannot carry, and neither passes in silence. A repository created inside the worktree — a scaffolded subproject, a vendored fixture, any git init — makes git add -A refuse the whole tree. The step fails and the worktree is kept, with its path in the error, because at that moment it holds the only copy of the work. Ignored files are skipped by git add -A by design and can never appear in a patch; they come back listed on the step's ignored field rather than vanishing with the worktree.
• The repository capture reads is the one pinned before the agent started. A worktree's .git is a one-line file naming its git directory, and it sits in the directory the agent spent the whole step writing to. That gitdir is read at worktree creation and passed explicitly to every later git call, so what capture diffs is not decided by a file the step could rewrite.

Host identity

(runtime, model) is an execution identity, not an agent id, and it comes from trusted startup configuration only — never a tool argument. runtime still comes from ORCHESTRATOR_HOST_RUNTIME, which stays the authority; naming it under host: is an assertion, and a mismatch refuses the boot.

model is the part the environment cannot supply. With it, a different model on the host's own runtime becomes routable. Without it, every agent on that runtime is excluded — today's consult behaviour. Write the versioned name: identity must be provably different, so opus and claude-opus are treated as claude-opus-5 and refused, and a name with no version at all is refused for being unprovable rather than assumed distinct.

review_policy is checked against this resolved identity too, so two agent ids pointing at one model are one reviewer however they are spelled.

Two calls per step

plan_step                    run_step | record_host_step
returns a preview       ──►  spends that step's token
and a one-time token         and runs or records it

There is no one-call form and no workflow-level token. One approval covering research, implementation, every fix round and every review would be an approval of nothing in particular. What a token proves is snapshot integrity — that the step being run is the step that was previewed, with the same agent, mode and inputs. It cannot prove a human saw anything, because MCP gives this server no channel to one; that depends on your client's tool-confirmation experience or an external gate.

A workdir must resolve beneath a configured root. / is never accepted and nothing is inferred from the working directory. A dirty tree is refused without allow_dirty.

A delegated step sees only what the host hands it

Nothing here reads your repository on an agent's behalf, so a delegated step starts with no code in front of it. orchestrator_workflow_plan_step(workflow_id, step, context) takes that material — the source of the files being changed, most of the time — and the host decides what goes in it. Without it, an implementation step has the plan and the brief and nothing to patch, and the honest models say exactly that instead of inventing a file they were never shown.

The material is redacted with the same scrubber as everything else before it is stored and before it is sent, and it is covered by the step's prompt hash, so the text the preview described is the text that goes out. A review step gets the same material its coding steps did.

Tests are observed, not claimed

A coding agent's statement that it ran the tests is retained as reported information; it is never the test result. A TestReport carries the exact command, working directory, exit code, bounded output, duration and the commit tested, plus reported_by, which the service assigns from which tool wrote the row and never reads out of a caller's payload. A host-written report is host-attested, and its provenance says so.

reported_by: orchestrator has exactly one source: a test step bound to isolated_write, where the exit codes come out of the CLI's own event stream rather than out of anything the model wrote. Read what that does and does not claim. It means every command the run reported returned zero — codex omits sandbox-denied commands from that stream, so it is not a claim that the project's suite ran. A contained test step that edited files while testing lists them on the report's changed_files; the worktree is deleted either way, so nothing there is applicable, but "the tests pass" and "the code was edited until they did" no longer look identical.

A failed test returns to fixing rather than advancing, unless advance_on_failed_test is set.

Two fields are cross-checked rather than stored side by side. A report cannot be passed with a non-zero exit code or with none at all — a command whose exit code was never read is skipped, which is what a denied command or a killed process produces — and it cannot be failed with a zero. The commit is stamped by the service from what the workflow currently holds, not taken from the payload: loop_done compares them, so a pass from an earlier round cannot carry a later one.

apply_patch is the one step whose whole job is a side effect on your tree, and the only evidence it happened is a commit that was not there before. Recorded without one, or with the commit it started from, the step is refused and marked failed rather than advancing — there is no applied: false to write, because a step that did not do its work is a failed step. Plan it again once the patch is applied and committed.

Where the loop stops

The review step goes through the review service — it does not write a synthesis straight into workflow storage, which would route around the guarantee that every serious finding survives. Findings gained a disposition (open, fixed, rejected, accepted_risk), because "unresolved finding" was previously not representable; rejecting or accepting the risk of a critical or important finding without a reason is refused.

loop_done is computed here, never asked of a reviewer. It is true only when the authoritative tests passed for the current commit, every reviewer's findings parsed and were retained, no critical or important finding is still open, missing_serious passed, and the workflow is in no exceptional state. Reaching max_fix_rounds with serious findings still open ends the workflow needs_attention — not completed.

A fix round after review carries the findings that are still open, read back from the review row rather than from workflow storage, so the round is an answer to the review and not a second pass at the goal. A fix triggered by a failed test before review instead carries that failed TestReport. A re-review is a recheck of the previous round's review (parent_review_id): the server appends that review's open findings and tells the reviewers to confirm or drop each one and to look for new problems only in the change. Send the fix's diff as the step's context, not the whole tree again.

The execution contract, honestly scoped

The coding prompt is assembled by this code: our EXECUTION_CONTRACT first, then the scope, accepted plan, authored brief and prior findings as a JSON payload. An authored brief is data inside that payload, and no field turns it into contract text.

That is code ownership, not a transport-level enforcement boundary. Claude Code has a real system-prompt channel; Codex, OpenCode, GitHub Copilot and Antigravity receive one compiled text, so there the ordering is a prompt convention a determined model could argue with. Saying so is more useful than overclaiming.

Security model

[!WARNING] Redaction covers every retained database copy, but what gets transmitted depends on the flow. An ordinary consultation sends its original material while storing a scrubbed copy. Reviews normally send the masked copy; secrets="send_as_is" is the explicit path that sends the original. Workflow step material is redacted before both storage and transmission. Detection is best-effort pattern matching rather than a scanner with perfect recall, so a secret with no recognizable shape can survive it. Keep the database private, or set store_full_content: false where the selected feature permits it.

Vendor history is outside all of this. Material sent to a reviewer also lands in that reviewer's own CLI history — Codex writes ~/.codex/sessions/, and the others keep their own logs. Orchestrator cannot redact or erase those files. It does read from them, in three places and for two fields: the Codex adapter opens the rollout file for the session it just ran to recover the model identity the CLI does not otherwise report, and opens the newest rollout to read the latest Codex CLI rate-limit numbers; the OpenCode adapter runs opencode export on the session it just ran, for the same reason — the model identity is absent from that runtime's event stream. Nothing else is taken from any of them. GitHub Copilot's is kept apart: its state lives under Orchestrator's own ~/.orchestrator-mcp/copilot/home, one session directory per consultation, which Orchestrator looks for before resuming a session and removes, with its lock, when it deletes that consultation, by a delete tool or by retention_days. It removes nothing else there, so the CLI's own store, session-store.db, keeps a copy of each prompt and answer until you delete the home. In that home it also reads mcp-config.json for the names of MCP servers to switch off, and writes one setting, disableAllHooks, into settings.json.

Two more limits worth knowing:

• CLI error text is shortened and common secret formats are redacted, but an unusual one may still appear in a returned error. Do not forward a raw error envelope somewhere untrusted.
• A caller-supplied JSON Schema is trusted input. A pathological regular expression in one can consume a large amount of CPU.

Orchestrator checks structure, routing, permissions, and model identity where observable. It cannot prove that a model's factual claims are true.

    nemotron-ultra:
      runtime: opencode
      command: opencode
      model: opencode/nemotron-3-ultra-free
      scores: { coding: 60, reasoning: 60 }

    copilot:
      runtime: copilot
      command: copilot
      model: auto
      scores: { coding: 60, reasoning: 60 }

Local dashboard

The optional dashboard shows agents, routing decisions, prompts, answers, usage, latency, errors, reviews, recorded fix rounds, and workflows. It is off by default because it can display everything stored in the consultation database.

consult:
  dashboard:
    enabled: true
    editable: false
    host: 127.0.0.1   # loopback only; `localhost` also works
    port: 8765        # 1-65535

A host that is not a loopback address is refused when the config loads, because the pages show every stored prompt and answer.

Start it separately:

ORCHESTRATOR_CONFIG=/absolute/path/to/config.yaml orchestrator-mcp-dashboard

Open http://127.0.0.1:8765, or wherever host and port point. The navigation has Monitor, Workflows, Reviews and Scorecard, all read-only; Agents and Reviewers appear only with editable: true.

/workflows lists every workflow; a workflow's page shows its state, fix rounds against the cap, the bindings frozen at start, and the step timeline in the order it happened, with each step linking to its consultation and its review. Those consultations are reachable nowhere else. The workflow pages are read-only: deletion stays on the MCP tools, where the confirmation token is.

/scorecard adds up each reviewer's answers and what became of its findings, the same numbers as orchestrator-mcp-server scorecard (?days=90 widens the window from 30). It only reads, so editable does not gate it.

Set editable: true to manage consult agents and reviewer selection in the browser. Browser-managed agents are written to ~/.orchestrator-mcp/agents.yaml; the dashboard never rewrites config.yaml, runs login commands, or starts consultations.

Both the MCP server and dashboard read configuration at startup. Restart them to pick up changes.

Configuration

ORCHESTRATOR_CONFIG points to the YAML file. If unset, the server looks for config.yaml in its working directory.

Spending ceilings

consult:
  spend:
    max_cost_usd_per_consultation: 2.0
    max_cost_usd_per_review: 5.0
    max_cost_usd_per_workflow: 25.0
    max_turns_per_consultation: 8
    max_turns_per_review: 12
    max_turns_per_workflow: 40

All six are optional and all are absent by default, which is no ceiling and no change in behavior. A consultation's ceiling is checked before each turn on it; a review's before each round of reviewers; a workflow's before each step, reviewers included, since the workflow is what paid for them. The check happens before the one-time token is spent and before any subprocess starts, so a refusal costs nothing and the same token still works once the ceiling is raised.

The three scopes nest, and a turn is refused by whichever it reaches first. The consultation pair is the one that bounds orchestrator_consult: that tool takes a consultation_id and resumes the session behind it, so every call after the first spends another turn against the same paid CLI. Reviewers and workflow steps are consultations too, so they are now bounded by their own ceiling as well as the ones above them.

What this buys is bounded, and the bound is the point: a request cannot be priced before it is made, so the guarantee is that the next request after the ceiling is crossed is refused, not that spend never exceeds the ceiling. A fan-out of five reviewers is one request in that sense.

An agent that reports no price contributes nothing to the total, which makes the total a floor. The refusal names those agents rather than presenting the floor as a sum. The error code is spend_limit_reached.

Set a turn ceiling too if anything in your routing is on a flat-rate plan. Codex, GitHub Copilot and Antigravity report no per-turn price, so a dollar ceiling over them counts nothing and never leaves $0.00 -- it reads as a bound and is not one. Turns are counted for every agent whatever it charges, so max_turns_per_review and max_turns_per_workflow bound the work that money cannot see. They are checked at the same moments, refuse with the same error code, and count the same way spend does: rebuilt from the turn ledger, so a retried reviewer counts every attempt exactly once.

A consultation with no turns yet is never refused. Nothing has been spent on it, so there is no ceiling for it to have reached -- what these stop is the turn after one.

Plans carry an estimate. A review plan and a workflow step preview show estimates (tokens and cost per agent) and estimated_cost_usd, fitted from that agent's last 50 successful turns on the same model. It is an estimate, not a quote: basis_turns says how many turns it rests on, an agent with no history gets none, and the cost is null for an agent with fewer than 3 priced turns -- so the total is null whenever any agent is unpriced, the same rule as above. When the estimate would reach a dollar ceiling the plan says so in ceiling_warning. That is advice only; refusals still read what was actually spent.

Watching a run

ORCHESTRATOR_LOG_LEVEL turns on stderr logging: routing decisions, child processes started and exited, leases taken and lost, reviewer fan-out, and workflow step transitions. WARNING by default, so an ordinary server is quiet; INFO or DEBUG when you want to see what a slow run is doing.

ORCHESTRATOR_LOG_LEVEL=INFO

Records go to stderr only, never stdout — stdout is the MCP transport, and a log line there is a corrupt protocol frame. Credential-shaped text is masked in the rendered line before it is written, on the same best-effort basis as the database copy.

The tools that can run for minutes — orchestrator_consult, orchestrator_consult_many, orchestrator_review_run, orchestrator_retry_review and orchestrator_workflow_run_step — also emit MCP progress notifications: a heartbeat every 15 seconds carrying elapsed time against the configured timeout, and agent or reviewer counts as each one answers. Clients that ask for progress see them; clients that do not are unaffected.

consult is the only top-level section. Configuration from releases before 0.4 containing capabilities, model_list, router_settings, or limits is rejected at startup because direct API routing was removed.

System requirements

• macOS or Linux. Windows is not currently tested.
• Python 3.11 or newer. CI currently tests 3.11 through 3.14 against the lockfile, and 3.14 against the newest release of every dependency.
• Homebrew or uv.
• A stdio MCP client such as Claude Code or Codex.
• At least one eligible configured agent. Ordinary consultation requires another runtime; reviews and workflows may use a provably different versioned model on the host's runtime.

Test it

The offline suite uses fake CLI agents. It needs no network and spends no model capacity:

uv sync
uv run pytest -q -n auto

Live smoke tests use the agents in your configuration:

ORCHESTRATOR_HOST_RUNTIME=claude uv run python smoke_consult_live.py
ORCHESTRATOR_HOST_RUNTIME=claude uv run python smoke_review_live.py
ORCHESTRATOR_HOST_RUNTIME=claude uv run python smoke_workflow_live.py

Live tests make real requests and may use paid capacity. Do not run them in CI unless that is intentional.

Troubleshooting

Deliberately not included

• No direct provider API routing or provider API-key configuration.
• No file edits, shell commands, MCP tools, or subagents for ordinary consulted agents; explicit web mode enables only the target runtime's web-search facility.
• No automatic fixes; the host agent owns edits and tests. A workflow records and validates the phases, it does not run the job unattended.
• No delegated write to your actual working tree. isolated_write runs in a throwaway worktree, and only where the runtime can be contained: Codex, and OpenCode where Orchestrator's OS-level sandbox holds. Claude Code, GitHub Copilot and Antigravity refuse it. The host applies every patch.
• No streaming; each consultation returns one complete envelope.
• No dashboard-initiated consultations.
• No automatic configuration reload.
• No multi-user or shared state.
• No account system for the loopback dashboard.

Contributing

Issues and pull requests are welcome.

1. Fork the repository and create a branch.
2. Make the change and add a test that fails without it.
3. Run uv run pytest -q.
4. Open a pull request.

Keep private configuration, login data, and consultation databases out of commits. For bugs, open an issue with the response envelope after removing paths, credentials, and other private information.

License

MIT · PyPI · GitHub issues · Privacy · Security

Built with Pydantic and the Python MCP SDK.