Quickstart

Quickstart

Get through the first Orcho run without learning every internal concept. The goal is simple: choose the smallest useful profile shape, run one mono task with live output, and know what a successful handoff looks like before you inspect the persisted evidence.

profile firstmono-run firstlive CLI outputsource checkout

first useful runmono-run

orcho run \
--project ~/www/my-workspace/my-project \
--task "Add input validation to the login endpoint." \
--output live

Start small. The first win is watching a profile-shaped lifecycle: plan, implementation, review, repair, and final acceptance.

Preview status

Package names and install commands may change before the first public release. Use the source-checkout path until published packages are available.

InputA Git project you can safely edit and the selected worker runtime commands available in the terminal.

RunOne repository, one task, one Orcho workspace beside the project.

Success signalThe live stream shows phase progress and a final decision; status, evidence, and git diff let you inspect it afterwards.

1. Prepare prerequisites

You need:

• Python 3.12 or newer;
• a Git project you can safely edit;
• the worker runtime commands selected by your profile available on PATH.

For a first run, use a branch or a copy of the project.

2. Check worker runtimes

A worker runtime is the code-agent CLI that Orcho invokes for a phase. Orcho owns the lifecycle, gates, evidence, recovery, and delivery decisions. The runtime does the local agent work.

Built-in runtime ids map to terminal commands:

Runtime id	Check command
claude	claude --version
codex	codex --version
gemini	gemini --version

Run the checks for the runtimes your profile or local config uses:

claude --version
codex --version

The default preview configuration can route different phases to different runtimes. If a selected runtime is missing, either install and authenticate its CLI, or override the phase runtimes in local config before running Orcho.

3. Install Orcho from source

git clone https://github.com/symphos-ai/orcho-core ~/orcho-preview/orcho-core
cd ~/orcho-preview/orcho-core
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
orcho --help

When packages are published, the install path will become:

pipx install orcho

4. Create a workspace

Keep the Orcho workspace next to the project, not inside it:

~/www/my-workspace/
├── my-project/
└── workspace-orchestrator/

Initialize the workspace:

orcho workspace init ~/www/my-workspace
source ~/www/my-workspace/workspace-orchestrator/orcho-env.sh

5. Run one mono task

This first path uses the smallest useful operating shape: one project, one task, one lifecycle, and evidence you can inspect afterwards. Deeper profiles can add more gates, review depth, participant sets, or control surfaces later.

If you are not sure which profile fits the task, use the manual feature path first. After that, read Profile advisor and try --profile auto-detect as an explicit recommendation step.

orcho run \
  --project ~/www/my-workspace/my-project \
  --task "Add input validation to the login endpoint. Return 400 if email is empty." \
  --output live

Start with a small task. The point of the first run is to watch the lifecycle: plan, implementation, review, repair, and final acceptance. --output live is the strongest first perception layer; it shows the run as it happens.

6. Inspect the recorded result

orcho status
orcho evidence --format md

Then inspect the project diff:

cd ~/www/my-workspace/my-project
git diff

7. Where to go next

Next intent	Read
Continue the light path	Watch the run → Read the result
Understand the operating model	Profile semantics → Profile advisor → Run lifecycle
Go deeper into operation	Correction follow-ups → MCP control surface
Open the expert layer	Runtime adapters → Profile and gate policy
See the full map	Docs map