ralph-rlm

An OpenCode integration that runs a persistent, self-correcting Ralph + RLM loop. Describe a goal in the TUI, walk away, and come back to protocol files and verify output — not a polluted chat history.

v0.2 is a provider-as-supervisor architecture: the revision plan (M0–M8) is implemented; see REVISION_PLAN.md for architecture detail and v0.3 roadmap.

v0.2 architecture

v0.2 exposes the loop as a custom OpenCode provider model (ralph-rlm/supervisor). You talk to one supervisor session. Behind the API, deterministic code owns verify, rollover, and worker lifecycle.

You — OpenCode TUI (model: ralph-rlm/supervisor)
        │  POST /v1/chat/completions (+ session bridge headers)
        ▼
packages/provider — Nitro :8787
  SupervisorAgent (LLM + tools)  →  LoopEngine  →  OpenCode SDK :4096
        │                                              │
        │                                              ▼
        │                         Worker sessions + ralph-worker plugin
        ▼
Protocol files (PLAN.md, RLM_INSTRUCTIONS.md, CURRENT_STATE.md, …)

The legacy monolithic plugin (.opencode/plugins-legacy/ralph-rlm.ts) remains for reference and is not loaded by default. Do not use ralph_spawn_worker() or ralph_create_supervisor_session() in v0.2.

Quick start

1. Install

git clone https://github.com/doeixd/opencode-ralph-rlm
cd opencode-ralph-rlm
bun install
bun run build   # optional; verify script builds packages

2. Configure your project

Copy plugins and config into your target repo (or develop inside this repo):

your-repo/
├── .opencode/
│   ├── plugins/
│   │   ├── ralph-worker.ts           # worker RLM tools + context gate
│   │   └── ralph-session-bridge.ts   # per-session LoopRun correlation (required)
│   ├── ralph.json                    # loop config (verify.command, maxAttempts, …)
│   └── ralph-provider.json           # supervisor LLM + worker agent defaults (optional)
├── opencode.json                     # register ralph-rlm provider
└── AGENT.md                          # optional static project rules (agentMdPath)

Register the provider in opencode.json — full example: .opencode/opencode.provider.example.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ralph-rlm": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ralph RLM",
      "options": {
        "baseURL": "http://127.0.0.1:8787/v1"
      },
      "models": {
        "supervisor": {
          "name": "Ralph Supervisor (loop orchestrator)"
        }
      }
    }
  }
}

Minimal .opencode/ralph.json:

{
  "enabled": true,
  "maxAttempts": 20,
  "verify": { "command": ["bun", "run", "test"], "cwd": "." },
  "gateDestructiveToolsUntilContextLoaded": true,
  "subAgentEnabled": true,
  "swarm": {
    "enabled": true,
    "maxConcurrent": 5,
    "unsafeEvalEnabled": false
  }
}

3. Start the provider

bun run ralph-serve
# optional: --port 8787 --opencode-url http://127.0.0.1:4096
#           --doctor --autofix --worktree /path/to/your/repo

Supervisor LLM credentials (provider process):

export RALPH_SUPERVISOR_API_KEY="..."
export RALPH_SUPERVISOR_MODEL="gpt-4o-mini"

Or .opencode/ralph-provider.json — see .opencode/ralph-provider.example.json.

4. OpenCode + supervisor model

opencode

Choose ralph-rlm/supervisor and delegate a goal:

Implement JWT auth; tests must pass when done.

The supervisor starts attempt 1 in the background. Ask status? anytime.

5. Verify setup

bun run ralph-serve -- --doctor --worktree .
# automated HTTP smoke (provider must be running with RALPH_TEST_MODE=1, or use --spawn):
bun run e2e-smoke -- --spawn

How the loop behaves

Each user message is a short supervisor turn. Long work runs in the background:

You:  Implement JWT auth; tests must pass
Model: Started loop — attempt 1 running. Ask for status anytime.

[background: worker → idle → verify → fail → rollover → attempt 2 → …]

You:  status?
Model: Attempt 2. Last verify failed. Worker idle. …

• Exit criterion: verify.command in .opencode/ralph.json (single source of truth for “done”).
• Memory: protocol files at repo root — not chat history.
• Workers: fresh OpenCode session per attempt; engine spawns via SDK.
• Worker plugin: gates edit/bash until ralph_load_context(); provides rlm_grep / rlm_slice.
• Permissions: bash/edit prompts appear in the worker session TUI (answer there).

Protocol files

Created on first start_loop (bootstrap) and updated across attempts:

Supervisor updates strategy via update_plan / update_rlm_instructions. Workers may patch PLAN.md / RLM_INSTRUCTIONS.md with ralph_update_plan / ralph_update_rlm_instructions when playbooks need to change mid-attempt.

Default agent instructions

v0.2 ships opinionated defaults so loops work without hand-authored prompts:

Customize without forking:

Tune RLM_INSTRUCTIONS.md and PLAN.md in your repo after the first failures — that is the durable steering surface for workers.

Supervisor tools (chat)

The provider supervisor LLM calls these internally — you steer in natural language.

Test mode (no external LLM): RALPH_TEST_MODE=1 bun run ralph-serve

Worker tools

Available in background worker sessions (ralph-worker plugin):

Swarm parallelism

Run side parallel agents alongside the main verify loop (does not replace verify.command):

Spawn parallel agents for auth, api routes, and test fixes.

The supervisor uses spawn_swarm with structured tasks. Caps: swarm.maxConcurrent, swarm.maxTasksPerRun, maxSubAgents in ralph.json.

Unsafe script eval (opt-in)

swarm_unsafe_runtime_code_eval runs supervisor-authored TypeScript in a subprocess with an injected OpenCode SDK client. Disabled by default.

{ "swarm": { "unsafeEvalEnabled": true } }

or RALPH_SWARM_UNSAFE_EVAL=1. Scripts are audited under .opencode/swarm/runs/<id>/. Prefer declarative spawn_swarm for normal use.

Session correlation

OpenCode does not forward session IDs to custom providers by default. Load ralph-session-bridge.ts so each TUI session gets its own LoopRun.

Confirm after your first supervisor message: response header x-ralph-session-source should be header:x-opencode-session-id, not anonymous. See GETTINGSTARTEDGUIDE.md § Session correlation.

Management API

With bun run ralph-serve running:

OpenAPI UI: http://127.0.0.1:8787/_scalar

Configuration reference

.opencode/ralph.json

Legacy keys (autoStartOnMainIdle, strategistHandoffMinutes, reviewer settings) remain in schema for compatibility but are ignored by the v0.2 provider.

Environment variables

Development and verification

bun install
bun run verify              # typecheck + 55 tests + Nitro build (CI uses bin/verify.ts)
bun run e2e-smoke -- --spawn   # HTTP smoke against ephemeral provider
bun run ralph-serve

Workspace packages:

• packages/engine — @ralph-rlm/engine
• packages/provider — @ralph-rlm/provider
• packages/worker-plugin — @ralph-rlm/worker-plugin

Contributor architecture: REVISION_PLAN.md · CI: .github/workflows/verify.yml

npm packages

v0.2 is a Bun workspace with scoped packages:

Recommended install today: clone this repo and run bun run ralph-serve, or copy .opencode/plugins/ + config into your project. Scoped npm publish is documented in the revision plan (M5.5 / M8.5).

Philosophy

• Fresh worker context each attempt — state in files, not chat history.
• Supervisor never edits repo code — workers implement; engine verifies.
• Grep-first RLM — rlm_grep → rlm_slice; large reference in CONTEXT_FOR_RLM.md.
• Verify is the contract — invest in a strong verify.command.

Based on Recursive Language Models (arXiv:2512.24601) and the Ralph overnight-loop pattern.

License

MIT (see package.json).