Getting started

Prerequisites

Requirement Used for Notes

Requirement	Used for	Notes
git	worktrees, branches, commits, merges	≥ 2.28 (`git worktree`); the target must be a git repository
Python	the whole kit	≥ 3.9; the kit imports `yaml` (PyYAML) always, and `langchain_core` / `langchain_openai` only for LLM-backed features
An agent CLI	doing the actual code changes	Default: `opencode` (OpenCode) configured with your model gateway. Any command works — `agent.cmd`
A model gateway	planner, consensus, contracts	OpenAI-compatible, per-model base paths (`gateway:` section); key via env var, `config.yaml`, or key file
Mail account (optional)	status reports + reply loop	SMTP + IMAP with an app password (E-mail loop and watch agent)

git

worktrees, branches, commits, merges

≥ 2.28 (git worktree); the target must be a git repository

Python

the whole kit

≥ 3.9; the kit imports yaml (PyYAML) always, and langchain_core / langchain_openai only for LLM-backed features

An agent CLI

doing the actual code changes

Default: opencode (OpenCode) configured with your model gateway. Any command works — agent.cmd

A model gateway

planner, consensus, contracts

OpenAI-compatible, per-model base paths (gateway: section); key via env var, config.yaml, or key file

Mail account (optional)

status reports + reply loop

SMTP + IMAP with an app password (E-mail loop and watch agent)

ralph_orchestrator/requirements.txt pins the Python dependencies:

PyYAML>=6
langchain-core>=0.3
langchain-openai>=0.2

Installation into the repository you want to change

From this repository:

./install.sh /path/to/target-repo

What install.sh does (verified behavior, install.sh):

Aborts if the target is not a git repository or already contains a ralph_orchestrator/ folder.
rsync -a --exclude pycache --exclude tickets.yaml of ralph_orchestrator/ into the target.
Creates a .venv-ralph virtualenv in the target and pip-installs requirements.txt into it.
Adds .ralph/ and .venv-ralph/ to the target’s git info/exclude (local-only ignore — no tracked file changes).
Prints the next steps.

Commit the kit in the target — worktrees branch from a commit, so the kit must be part of the history:

cd /path/to/target-repo
git add ralph_orchestrator && git commit -m "add ralph orchestrator"

First-run procedure

PY=.venv-ralph/bin/python

# 1. Interactive setup: config check, agent CLI check, gateway reachability,
#    dependency + plugin install. Hard-stops with a message on the first problem.
$PY ralph_orchestrator/orch.py wizard

# 2. (only if you skipped the wizard's install step)
$PY ralph_orchestrator/orch.py preflight --ping

# 3. Write the specification, generate the plan, review it
$EDITOR ralph_orchestrator/SPEC.md
$PY ralph_orchestrator/orch.py plan           # SPEC.md -> ralph_orchestrator/tickets.yaml
$EDITOR ralph_orchestrator/tickets.yaml       # review the plan - it is the contract
$PY ralph_orchestrator/orch.py check          # DAG validity, waves, useful agent count
$PY ralph_orchestrator/orch.py graph          # Mermaid view of the DAG

# 4. Execute (resumable) and observe
$PY ralph_orchestrator/orch.py run
$PY ralph_orchestrator/orch.py dashboard      # second terminal: http://127.0.0.1:8471
$PY ralph_orchestrator/orch.py status

The result is the branch ralph/integration (created from your configured base_branch). Review the diff and merge it yourself — the kit never touches your base branch, and pushing is off by default (orchestrator.push: false).

The wizard is documented step by step in Orchestrator — the wizard; the e-mail loop setup (optional) is in E-mail loop and watch agent.

Minimal working example without any LLM

If you want to see the loop before committing to models and keys, use the offline showcase in mockup/ — it runs the real orchestrator with a shell-script "agent", needs no gateway and no e-mail, and finishes in a couple of minutes.

Running the test suite of the kit itself

pip install -r ralph_orchestrator/requirements.txt pytest
pytest -q        # from this repository's root

The suite runs the full scheduler/worker/merge/guard/consensus/planner/mail/watch/wizard behavior with fake agents and fake LLMs — no network and no models needed. Details in Verification and tests.