Orcho

Orcho is a production harness and local-first control plane around AI coding workers.

Run one task. Watch Orcho plan, implement, reject false-ready work, repair it, and prove what is ready to deliver.

📖 Documentation: docs.orcho.dev

This package is the recommended installer for the public Orcho command set. It installs the full set by default — the core CLI (orcho-core) and the MCP server (orcho-mcp). For a minimal engine-only install, depend on orcho-core directly.

Those are the two ways to drive Orcho, and both come with this package.

Drive it yourself — the CLI

_{orcho run end to end (mock pipeline, sped up): plan → validation → implement → review → final acceptance → delivery, with a live phase stream and an evidence rollup.}

Let your agent drive — MCP

_{The same run, driven by an AI client (here Claude Code) through the MCP server — orcho_run_start → orcho_run_watch → orcho_run_evidence → verdict, all typed, no log scraping.}

_{Both runs above are mock=True. Interactive, pausable versions: docs.orcho.dev.}

Install

Pick the install path by how isolated you want the run to be:

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: isolated CLI install

Use pipx when you want Orcho commands available from your shell without installing Orcho into the current project or Python environment.

pipx install orcho

This installs the core commands plus the MCP server:

orcho --help
orcho-run --help
orcho-cross --help
orcho-mcp --help

Engine and core CLI only, without the MCP server:

python -m pip install orcho-core

orcho[mcp] and orcho[all] remain as back-compat aliases; since 0.1.1 they install the same set as plain orcho.

Upgrading

orcho update resolves the installer that owns the environment Orcho is running from and upgrades through it:

orcho update

Add --dry-run to see the detected install and the upgrade command without running it. Orcho delegates to the detected manager rather than reimplementing one, so you can always run the equivalent command yourself:

Editable installs and source checkouts are reported, not upgraded: there the checkout is the upgrade unit, so update it with git pull instead.

Try without installing: Docker

Use Docker when you want to run Orcho in an isolated container while mounting only the current project and an explicit credential directory.

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."
orcho status

See docker/README.md for the one-time credential bootstrap, MCP stdio setup, and project-toolchain extension pattern.

Alternative: project-managed environment

Use pip when you intentionally want Orcho inside the active virtual environment, CI image, devcontainer, or Docker image.

python -m pip install orcho

Commands

orcho --help
orcho-run --help
orcho-cross --help
orcho-mcp --help

Package Layout

• orcho-core provides the core engine and CLI.
• orcho-mcp provides the MCP server.

This package only coordinates installation and command dispatch.