ouroboros_ralph
Start a background evolution loop that iteratively runs evolve steps until QA passes, convergence is reached, or max generations are hit, returning a job ID for status checks and cancellation.
Instructions
Start a first-class Ralph loop in the background. The loop repeatedly runs evolve_step until QA passes, convergence is reached, a terminal evolution action occurs, cancellation is requested, or max_generations is reached. In non-plugin runtimes, returns a job_id immediately for ouroboros_job_status, ouroboros_job_wait, ouroboros_job_result, and ouroboros_cancel_job. In OpenCode plugin mode, returns job_id=None and delegates the loop to the plugin child session.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| execute | No | Whether each generation should execute and evaluate. Default: true. | |
| skip_qa | No | Skip post-execution QA. Default: false. | |
| parallel | No | Whether each generation may execute ACs in parallel. Default: true. | |
| lineage_id | Yes | Lineage ID to start or continue. | |
| project_dir | No | Project root forwarded to each evolve_step generation. | |
| execution_id | No | Optional execution id used for checkpoint commit metadata. | |
| seed_content | No | Seed YAML content for generation 1. Omit for continuation. | |
| commit_policy | No | Optional checkpoint commit policy forwarded to evolve_step. | |
| auto_session_id | No | Optional auto session id used for checkpoint commit metadata. | |
| max_generations | No | Maximum generations to run before stopping. Default: 10. Range: 1-10. | |
| max_total_seconds | No | Total wall-clock budget for the entire Ralph loop in seconds. In the in-process runner this is enforced by RalphLoopRunner: checked at the top of every iteration BEFORE launching evolve_step, and on exhaustion the loop stops with stop_reason='wall_clock_exhausted'. In OpenCode plugin mode the bound is forwarded to the child session and the plugin is expected to self-enforce; the MCP server cannot abort a foreign child process. When omitted, a derived ceiling of max_generations * per_iteration_timeout_seconds is auto-applied (with a WARNING log) for standalone callers. Range: 1-86400. | |
| checkpoint_commits | No | Existing checkpoint commit records forwarded to evolve_step. | |
| oscillation_window | No | Number of trailing iterations whose findings_hash must match (and QA must not have passed) to stop with stop_reason='oscillation_detected'. Default: 3. Range: 2-10. Values < 2 are rejected because a single iteration cannot oscillate with itself. | |
| conductor_directive | No | Deterministic non-relaxing directive for one successor generation. | |
| conductor_decision_id | No | Selected conductor decision authorizing one successor generation. | |
| grade_regression_window | No | Number of trailing iterations whose non-None grades must strictly decrease to stop with stop_reason='grade_regressing'. Default: 2. Range: 2-10. Values < 2 are rejected because strict-decrease requires at least two grades to compare. | |
| predecessor_execution_id | No | Execution or generation that this successor follows. | |
| checkpoint_attempted_ac_ids | No | Acceptance criteria already considered for checkpoint commits. | |
| per_iteration_timeout_seconds | No | Per-iteration wall-clock bound in seconds. In-process runtime: hard-enforced via asyncio.timeout, the loop stops with stop_reason='iteration_timeout' on expiry. OpenCode plugin runtime: advisory bound advertised to the child session via prompt + subagent context — the child is expected to honor it and return stop_reason='iteration_timeout', but the parent MCP process cannot interrupt the child, so a non-conforming child session may still exceed this bound. Default: 1800. Range: 30-7200. |