Ralph Orchestrator

Ralph Loop Orchestra

Ralph Orchestrator is a drop-in kit for a git repository. You write what must be true (a specification); the kit turns it into a structured modification plan (a DAG of tickets, each with an executable acceptance command and a file scope) and executes that plan with parallel autonomous coding agents — one git worktree and branch per ticket — merging only what both an independent LLM review panel and each ticket’s acceptance command approve.

The kit is named after the "Ralph loop" (https://ghuntley.com/ralph/): an agent that works in a loop against a completion gate, never self-certifying.

Main capabilities

  • Dependency-aware scheduling — tickets declare depends_on; the orchestrator runs the ready set with a dynamic agent count (pending tickets weighted by complexity, capped by configuration). Tickets whose file scopes overlap are never run in parallel.

  • Completion gate, no self-certification — a ticket merges only when its changes stay inside its scope, its accept shell command exits 0 (run by the orchestrator, never the agent), the review panel votes quorum, and the project regression suite passes on the integration branch after the merge (the merge is undone otherwise).

  • Independent review panel — several different LLM reviewers vote on each diff (and on interface contracts and change requests). A model never reviews its own ticket.

  • Agent collaboration — parallel agents that never share a context agree on interfaces first (contract negotiation), talk through a file-backed message bus, and can request changes to already-merged tickets (a review panel decides; approved requests become follow-up tickets).

  • E-mail loop — periodic plain-text status mails and a final report with the interactive HTML report attached. Replies to the mail go back into the loop: mentioned tickets receive the reply as feedback, and a reply to a blocked ticket unlocks it. An always-on watch agent handles the gaps between runs.

  • Live dashboard — a dark, self-contained web UI (workflow graph, tasks, agents & models, plugins, start-time × duration timeline) polling the same state file the orchestrator writes, plus a self-contained HTML/PDF run report.

  • Resumable state — everything runs against .ralph/state.json; a crashed or interrupted run resumes from where it stopped, with real wall-clock event history.

Primary components

Component File(s) Responsibility

Orchestrator (CLI, scheduler, merger)

ralph_orchestrator/orch.py

All commands, the run loop, serial merge into the integration branch, wizard, watch agent

Worker

ralph_orchestrator/worker.py

One ticket to a reviewed, accepted commit: worktree, agent process, scope guard, acceptance, handoff

Review panel

ralph_orchestrator/consensus.py

Quorum voting on diffs, contracts and change requests

Collaboration

ralph_orchestrator/collab.py, bus.py, contracts.py

Message bus, contract-first negotiation, change-request follow-up tickets

Planner

ralph_orchestrator/planner.py

Specification + repository overview → validated tickets.yaml (LLM)

State

ralph_orchestrator/state.py

Resumable run state + structured event recording

E-mail

ralph_orchestrator/report.py, mail_check.py, mail_reply.py

Status mails, webhook, reply capture and consumption

Presentation

ralph_orchestrator/html_report.py, dashboard.py, pdf_report.py

Shared snapshot document, live dashboard server, optional PDF rendering

See Architecture for the full component map and runtime data flow.

Supported technologies and standards

  • Python ≥ 3.9. The runtime core (scheduler, worker, state, bus, dashboard, e-mail) is stdlib
    PyYAML; LangChain (langchain-core, langchain-openai) is used only for the LLM-backed features (planner, consensus, contracts).

  • git ≥ 2.28 (worktrees, branches). All repository state the kit creates lives under the target repo’s .ralph/ directory and out/ reports.

  • OpenAI-compatible model gateway (base URL templated per model) for the LLM calls.

  • Agent CLI: any command that edits files in its working directory — the default is opencode run (OpenCode), configured in agent.cmd.

  • SMTP (587 STARTTLS / 465 SSL) and IMAP (993 SSL / 143 STARTTLS) for the e-mail loop; optional Teams/Slack/ntfy webhook (JSON {"text": …​}).

  • Optional Playwright headless Chromium for PDF rendering of the run report.

Quick start

A two-minute, fully offline demonstration (no models, no keys, no internet — a shell script plays the "AI agent"):

cd mockup/demo-repo
python3 -m pip install PyYAML
./setup.sh
python3 ralph_orchestrator/orch.py run

A real run: install the kit into the repository you want to change, run the wizard, plan, and execute — see Getting started.

Documentation map