orchestrator-mcp

Orchestrator MCP is a local Model Context Protocol server that lets one coding agent consult another. It launches the Codex, Claude Code, OpenCode, 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.

Before / After

1. Copy the prompt, diff, and context.

2. Open another coding agent.

3. Recreate the task and paste everything.

4. Bring the answer back.

5. Repeat when you need a follow-up.

1. Call orchestrator_consult.

2. Get the other agent's structured answer.

3. Reuse consultation_id for follow-ups.

The conversation stays connected from the same client.

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  ──►  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.

Related MCP server: ML Task Router MCP Server

Install

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.

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.

2. Create config.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-4-6
      priority: 10
      web_search: true
      scores: { coding: 90, research: 95, writing: 95, review: 95 }

See config.example.yaml for a broader annotated configuration, an OpenCode agent, and an experimental Antigravity example.

3. Add the server to your MCP client

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

Add this to ~/.codex/config.toml:

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

Restart the MCP client after changing its configuration.

Run with uvx instead

No permanent server install is required:

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

For Codex:

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

The PyPI distribution is named orchestrator-mcp-server; the shorter PyPI name belongs to another project.

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.

Every argument is optional; a command with none expands into an instruction to ask you for the missing part. 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.

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. 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

Request fields:

Agent configuration:

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 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 is restricted to these trees

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.

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.

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 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.

Reviews default to web: false. Reviewers cannot change files or run commands. orchestrator_apply_fixes is a plan for work the host agent performs; it never applies a patch itself.

Credential-shaped values are masked before storage. secrets="send_as_is" is an explicit escape hatch for a false positive: it requires the exact original goal and context again, sends those originals to the reviewers, and still stores only the redacted copy.

store_full_content: false does not apply here in full. A review's goal and context are stored either way — the second half of the approval handshake reads them back to send what was approved — and reviewer answers and findings are not. That leaves nothing to prove every Critical survived synthesis, so orchestrator_finalize_review refuses, and the review stays at awaiting_synthesis. Finalization is refused on the same grounds when a reviewer answered only in unparseable prose, or when its findings were truncated.

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: deepseek-flash, 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.

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.

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 gets the open findings too.

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 and OpenCode 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.

A workflow deletes whole or not at all. Its consultations are excluded from every consultation delete path and orchestrator_delete_review refuses a review that is a workflow step, because a step pointing at a row that is gone still reads as intact — and the next fix round would answer from the goal instead of from the review. So these three tools are the only way any of those rows leave the database.

A review step's reviewers come from its binding, so a workflow needs no review: block unless that binding is left to auto — then it falls back to the configured reviewers and refuses without them.

A workflow's consultations are not reachable from the public tool: resuming one by its consultation_id is refused with workflow_owned_session. Steps take a lease, so a crashed run resolves rather than leaving a status that outlives its process.

Patch integrity. Redaction can rewrite credential-shaped text, and a rewritten patch is a corrupt patch. SQLite stores only a sanitized audit copy plus the sha256 of the raw patch. The applicable patch is kept in a private 0600 recovery file and returned by workflow status until apply_patch is recorded, then every raw patch from that workflow round is removed. If the recovery copy cannot be written or trusted, the raw response is still returned and recovery_warning explains that status cannot recover it later. After the host applies it, the resulting code commit becomes the workflow's review input. Recovery files and retained failure worktrees expire after seven days. The first workflow-service open schedules a bounded, best-effort background sweep of owned artifacts older than that window, so abandoned work does not become indefinite raw storage or request latency.

Security model

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.

OpenCode is one CLI in front of many hosted providers, which is how models the other three runtimes do not carry become reachable without Orchestrator holding a key. Models are addressed as provider/model:

    deepseek-flash:
      runtime: opencode
      command: opencode
      model: opencode/deepseek-v4-flash-free
      scores: { coding: 60, reasoning: 60 }

Hosted providers only. Orchestrator does not run a model on your machine, or on anyone's. Depending on the selected model, this runtime consults a subscription you already hold or OpenCode's anonymous free tier. A locally served model — Ollama, LM Studio, your own endpoint — cannot be reached through it, and that is enforced by construction rather than by a check: a consultation runs under a configuration with no provider block at all, and a provider block is the only place an endpoint outside OpenCode's own catalogue is ever named. Verified against the CLI: under this configuration --model ollama/qwen2.5:7b fails with ProviderModelNotFoundError and the local server is never contacted. The constraint is real — if the model you want is one you host yourself, this runtime cannot consult it.

Readiness is asked under that same configuration. Orchestrator runs opencode models with your global config out of reach and checks that the agent's provider/model is listed, so readiness answers the question the consultation will actually ask rather than reporting a model that would then fail to resolve. A provider that needs a credential wants opencode auth login once; stored keys and OAuth tokens live in OpenCode's data directory, which Orchestrator neither reads nor relocates. The child gets a fixed allowlist of environment variables — HOME, PATH, LANG and a few more — and every *_API_KEY in this server's own environment is excluded from it.

Each consultation runs under a configuration Orchestrator writes and nothing crosses over from your own: permissions denied outright, no MCP servers, no plugins, no instructions, no project agents, no providers, sharing and auto-update off. OPENCODE_CONFIG merges rather than replaces, so XDG_CONFIG_HOME is pointed at an empty directory as well — your global config is out of reach, not merely outranked.

The working directory is ~/.orchestrator-mcp/opencode/<agent>, mode 0700 with the configuration files 0600, holding nothing else. One per agent rather than one shared: the files are identical for every agent today, and one release that gives an agent something of its own to write would turn that into a race between a consultation starting and reading its configuration. Under $HOME rather than /tmp deliberately: Orchestrator refuses to run if it finds an opencode.json or opencode.jsonc above that directory — a parent's permissions outrank its own — and that check can only run before OpenCode reads the chain, so every ancestor needs to be a directory no one else can write to. It is not deleted afterwards, and cannot be: OpenCode records a session's directory and re-resolves it on resume, so a per-run temporary directory would break every follow-up turn.

Two limits worth knowing before you enable it:

• Web search is not supported in this runtime. source_mode: web is refused whatever web_search is set to, rather than being served a model-mode answer under a web-mode contract.

• opencode run exits 0 even when it fails, so success is judged from the event stream. A run that produces no answer is reported as a failure rather than as an empty one.

There is no schema flag on this runtime, unlike the other three, so the response shape is stated in the prompt. A model that returns malformed JSON is asked once more in the same session, and a second failure ends the consultation.

Antigravity (agy) uses its own login and OS keyring, but its isolation is weaker than Codex or Claude Code:

• It inherits MCP servers from your agy settings. Headless mode denies tools by default, and Orchestrator fails the consultation if a tool step is reported, but this is detection rather than prevention. Do not enable it if you loosened headless permissions.

• It accepts prompts in process arguments rather than standard input. Other users on a shared machine may be able to read those arguments while the process runs.

• It has no login-status command, so readiness is reported as unverified until a real request succeeds or fails.

Large prompts are split across turns because Linux limits one argument to 128 KiB. Gemini models have handled this transport in testing; some non-Gemini models may reject the fragments as prompt injection. reasoning_effort and web mode are not available for this runtime.

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

Start it separately:

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

Open http://127.0.0.1:8765.

/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.

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.

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, 3.12, and 3.13.

• 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

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 is codex-only; every other runtime refuses it, and 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

Built with Pydantic and the Python MCP SDK.