Skip to content
Orcho Docs

Runtime adapters

Orcho uses runtime adapters to call worker agents.

The runtime does the local agent work. Orcho owns the lifecycle around it: planning, phase boundaries, review, evidence, recovery, and delivery decisions.

What counts as a runtime?

Section titled “What counts as a runtime?”

A runtime is a local command-line worker that Orcho can invoke from a project checkout. It is not an IDE panel, web chat, or manual copy-paste session.

For a run to work, the selected runtime command must be available on PATH and already authenticated for non-interactive use.

Built-in runtime ids:

Runtime idTerminal commandRole in Orcho
claudeclaude --versionWorker backend for phases that route to Claude.
codexcodex --versionWorker backend for phases that route to Codex.
geminigemini --versionWorker backend for phases that route to Gemini.

The profile does not mean “one runtime for everything.” A profile can route different phases to different runtimes and models. For example, planning, implementation, review, repair, and final acceptance can each have their own runtime/model choice.

First-run check

Section titled “First-run check”

Before the first real run, check the commands your selected profile uses:

Terminal window
claude --version
codex --version

If a command is missing, the fix belongs at the runtime boundary:

  • install the missing CLI;
  • authenticate it;
  • expose it on PATH;
  • or override the phase runtime to one that is installed.

The run should fail because a worker is unavailable, not because the operator has to guess which hidden dependency was missing.

Adapter boundary

Section titled “Adapter boundary”

A runtime adapter should answer:

  • how to invoke the worker;
  • how to pass prompt input;
  • how to capture output;
  • how to preserve or reset session context;
  • how to report runtime failures.

It should not own:

  • final readiness policy;
  • delivery scope;
  • correction routing;
  • evidence schema;
  • workspace topology.

That boundary is what lets Orcho use different workers without becoming just another worker.

Phase-level routing

Section titled “Phase-level routing”

Runtime selection is phase-level policy. A local config can choose different workers for different jobs:

{
  "phases": {
    "plan": { "runtime": "claude", "model": "claude-opus-4-8[1m]" },
    "implement": { "runtime": "claude", "model": "claude-opus-4-8[1m]" },
    "review_changes": { "runtime": "codex", "model": "gpt-5.5" },
    "final_acceptance": { "runtime": "codex", "model": "gpt-5.5" }
  }
}

This is why the quickstart asks you to check the selected runtime commands instead of saying that one installed agent is always enough.

Section titled “Related”