orcho-core 0.2.0

Local-first control plane for cross-agent AI software delivery

Orcho — Multi-Agent Pipeline Engine

Orcho — local-first control plane for agentic software delivery.

📖 Documentation: docs.orcho.dev

_{One orcho run end to end (mock pipeline, sped up). Interactive version with pause and scrub: docs.orcho.dev.}

Use the coding agents you already trust; Orcho supervises the workflow around them: plan → implementation → review → repair → final acceptance.

It is built for work that needs more structure than a single interactive agent session:

• one task or one coordinated change across several repositories;
• explicit phase topology through profiles;
• human/agent review gates with resume and retry;
• durable run state: plans, diffs, findings, metrics, evidence;
• CLI, SDK, and MCP control surfaces.

Which model runs which phase is fully configurable. Default: Claude (PLAN / BUILD / FIX) + Codex (REVIEW / QA). Assign Claude, Codex, or Gemini to any phase via env vars, profiles, or config.local.json.

Zero project-specific code — all project context comes through plugin.py.

---

Try the golden mock demo

The fastest zero-API proof is the single-project CLI demo. It creates a disposable git-backed fixture, runs the full mock pipeline, reviews the diff, and writes evidence:

examples/scripts/bootstrap_demo_1a.sh

Then paste the printed orcho run ... --mock command and inspect:

orcho evidence --format md --workspace /tmp/orcho_demo_1a/workspace-orchestrator
orcho status --workspace /tmp/orcho_demo_1a/workspace-orchestrator
orcho diff <run-id> --stat --workspace /tmp/orcho_demo_1a/workspace-orchestrator

Full walkthrough: docs/demos/demo-1a-single-project-cli.md.

---

First time? Start here

→ docs/user/00_getting_started.md

The full path from zero to the first result: prerequisites → install → connect your project → first run.

---

Install

Choose an install path:

Path	Use when	Command
Native CLI with pipx	You want Orcho commands on your shell PATH without installing them into a project environment.	pipx install orcho
Docker	You want an isolated container for trying Orcho, running CI-like checks, or exposing orcho-mcp over stdio.	docker pull ghcr.io/symphos-ai/orcho
Direct package dependency	You intentionally want only the engine package in a virtualenv, CI image, devcontainer, or custom image.	python -m pip install orcho-core

If pipx is missing, install it first. On macOS with Homebrew:

brew install pipx
pipx ensurepath
exec zsh -l

For Linux or Windows, use the official pipx installation guide.

Recommended CLI install

Use the orcho distribution when you want the public command set available from your shell. pipx keeps the CLI isolated from the current project or Python environment.

pipx install orcho
orcho --help

Since orcho 0.1.1 this installs the full set — the core CLI and the MCP server (orcho-mcp). The [mcp]/[all] extras remain as no-op back-compat aliases.

Containerized install

Use Docker when you want to try Orcho without installing its Python package or agent CLIs on the host:

docker pull ghcr.io/symphos-ai/orcho
alias orcho='docker run --rm -it \
  -v "$PWD":/workspace \
  -v ~/.orcho-auth:/agent-auth:ro \
  ghcr.io/symphos-ai/orcho orcho'

orcho run --project /workspace --task "Add input validation to the login endpoint."

The container image includes the core CLI and MCP server. See orcho Docker docs for credential bootstrap, MCP stdio setup, and custom project toolchains.

Direct engine dependency

Use pip when you intentionally want orcho-core in the active virtual environment, CI image, devcontainer, or Docker image.

python -m pip install orcho-core

The orcho distribution depends on orcho-core; most CLI users should start with orcho, while integrators can depend on orcho-core directly.

For source checkout setup, tests, and contribution workflow, see CONTRIBUTING.md.

---

How it works

Task
  → Claude  [PLAN]              writes the implementation plan
  → Codex   [validate_plan]     audits the plan
  → Claude  [BUILD]             implements the code
  → Codex   [REVIEW]            reviews the diff
  → Claude  [FIX]               fixes the findings
  → Codex   [final_acceptance]  final verdict

---

Core commands

# One project
orcho run --task "Add input validation to /api/login" --project ~/my-project

# Several projects at once
orcho cross --task "Add rate limiting: API + client" \
            --projects api:~/api client:~/client

# No API calls (test)
orcho run --mock --task "..." --project ~/my-project

# Plan only (no code)
orcho run --profile planning --task "..." --project ~/my-project

# Resume an interrupted run
orcho run --resume 20260503_104135

# Status, history, metrics
orcho status | orcho history | orcho metrics

---

Connecting a project

Create your-project/.orcho/multiagent/plugin.py:

from pipeline.plugins import PluginConfig

plugin = PluginConfig(
    name="My Project",
    tech_stack="FastAPI + PostgreSQL",
    architecture="REST API. Routes: app/routes/, Services: app/services/",
    file_hints=["app/routes/", "app/services/", "tests/"],
    build_prompt_extra="Run: pytest -x after changes.",
    review_focus_extra="Check N+1 queries, missing validations.",
)

Without plugin.py, orcho runs in generic mode.

---

Package layout

orcho-core/
├── cli/                            ← CLI facade (orcho run / cross / status…)
├── sdk/                            ← typed headless API for tools and embedders
├── pipeline/
│   ├── project_orchestrator.py     ← single-project pipeline
│   ├── cross_project/              ← cross-project planning, dispatch, gates
│   ├── runtime/                    ← profiles, steps, state, runner
│   ├── prompts/                    ← composable prompt parts and contracts
│   ├── control/                    ← handoff, resume, operator decisions
│   ├── engine/                     ← sessions, logging, worktrees, run diff
│   ├── evidence/                   ← evidence bundle and renderers
│   ├── profiles/                   ← profile loading and validation
│   ├── sandbox/                    ← command isolation backends
│   ├── skills/                     ← skill discovery and injection
│   ├── plugins.py                  ← PluginConfig + load_plugin()
│   └── checkpoint.py               ← SQLite store (--resume)
├── core/
│   ├── _prompts/                   ← core prompt templates
│   ├── _config/                    ← packaged defaults
│   ├── contracts/                  ← plan/review/release schemas
│   ├── infra/                      ← config, platform, binary discovery
│   ├── observability/              ← logging, metrics, trace
│   ├── io/                         ← retry, git helpers, prompt loader
│   └── context/                    ← codemap builder (optional)
├── agents/                         ← runtimes, registry, stream parsers
└── tests/                          ← unit, integration, acceptance, SDK contract tests

---

Documentation

The user-facing portal is docs.orcho.dev — start there.

The in-repo docs below are the contributor & deep reference: the canonical engineering contracts the portal links into. Ordered from general to specific.

Level	For whom	Link
User	You want to use the system	docs/user/
Expert	You tune prompts, plugins, and models	docs/expert/
Integrator	You author profiles, gates, and adapters	docs/guides/
Reference	Exact schemas and registries	docs/reference/
Creator	You develop the engine itself	docs/creator/

Full index: docs/README.md.

---

Testing

pytest tests/ -q
pytest tests/unit/ -v
pytest tests/integration/ -v

Tests must not call real models. Use MockAgentProvider for pipeline-flow scenarios.

---

Key principles

• Zero hardcoding — all project context comes through plugin.py
• DRY engine — pipeline/engine/ is shared by both orchestrators
• 3-level prompts — project → workspace → core (always overridable)
• Discoverable extension points — workspace init creates safe .orcho/ guides and templates without overwriting local edits
• Resumable — --resume continues from the last checkpoint
• Cross-platform — macOS, Linux, Windows (native + WSL2)