2-minute offline showcase

The mockup/ directory contains a self-contained demonstration that runs the real orchestrator against a dummy "AI agent": a plain shell script (mockup/demo-repo/agent.sh) that implements its ticket with cat > file. No OpenCode, no model gateway, no e-mail, no internet — only git and python3 with PyYAML (a run with consensus.enabled: false and collaboration.bus/contracts: false never imports LangChain).

What the showcase demonstrates

The showcase plan (mockup/demo-repo/tickets.demo.yaml) is a 4-ticket DAG:

T1 (create greet.py)
 ├──> T2 (farewell in greet.py)   ┐  run in parallel (peak agents: 2)
 └──> T3 (cli.py, greeting only)  ┘
        T2 + T3 ──> T4 (cli.py also prints the farewell)

Each ticket has an executable accept command (e.g. python3 -c "import greet; assert greet.farewell('Ralph') == 'Goodbye, Ralph!'") and a file scope. The orchestrator creates a git worktree and branch per ticket, enforces the scope, runs the acceptance command itself, merges into ralph/integration in dependency order, and keeps live state for the dashboard.

Run it

cd mockup/demo-repo
python3 -m pip install PyYAML        # the only dependency for this consensus-free run

./setup.sh                           # copies the kit in (like install.sh), git init + commit; idempotent

python3 ralph_orchestrator/orch.py run

setup.sh copies ../../ralph_orchestrator/ into the demo repo, installs the showcase config (config.demo.yaml → ralph_orchestrator/config.yaml) and the showcase tickets (tickets.demo.yaml → ralph_orchestrator/tickets.yaml), and creates the git history with an explicit author identity so it works on any machine.

Verified output (abridged, from an actual run of this repository):

T1: merged (1/4)
T2: merged (2/4)
T3: merged (3/4)
T4: merged (4/4)
Run report written to .../out/run_report.html
[report] [ralph] DONE: 4/4 merged, 0 running, 0 blocked  (not sent)  (report attached)

python3 ralph_orchestrator/orch.py status afterwards reports agent runs: 4 peak agents: 2 reason: DONE — the peak agents: 2 is T2 and T3 running concurrently, exactly what the DAG allows (their scopes are disjoint).

Watch it

In a second terminal — while the run is in progress, or after it (state persists in .ralph/state.json):

python3 ralph_orchestrator/orch.py dashboard     # http://127.0.0.1:8471

The Timeline view shows one bar per ticket with real wall-clock start/finish — T2 and T3 overlap because they ran in parallel. The run report (out/run_report.html) is also generated and is a self-contained file you can open directly.

Reset

git worktree prune
rm -rf .ralph out greet.py cli.py
git checkout -- .
git branch -D ralph/integration ralph/T1 ralph/T2 ralph/T3 ralph/T4 2>/dev/null

or simply delete demo-repo/ and copy it again from mockup/.

Turning the showcase into a real run

  1. Replace agent.cmd in ralph_orchestrator/config.yaml with a real agent CLI, e.g. opencode run -m "$RALPH_MODEL" "$(cat "$RALPH_PROMPT_FILE")".

  2. Put real provider/model ids in agent.models (S/M/L).

  3. Fill the gateway: section (key) and set consensus.enabled: true to enable the LLM review panel (Consensus review panel).

  4. Replace the demo tickets with your own plan — orch.py plan or hand-written (see templates/tickets.example.yaml).

The dummy script is the entire "intelligence" of the showcase. Everything else — scheduling, worktrees, scope enforcement, acceptance, consensus hooks, merging, state, dashboard — is the real framework.