ralph-rlm

An OpenCode integration for long-running, hands-off coding work. Describe a goal, walk away, and come back to finished work. Behind the scenes a fresh agent keeps working in a loop — checking itself against your tests after every attempt — until the job is actually done.

It combines two ideas:

• Ralph — the "just run the agent in a loop until it's done" technique (ralph-wiggum.ai). Instead of one long, drifting chat, each attempt starts with a fresh agent whose real memory lives in files on disk. Simple, relentless, and surprisingly effective for overnight-style runs.
• RLM (Recursive Language Models) — instead of stuffing huge reference material into the context window, the agent treats it as a store it greps and slices on demand (arXiv:2512.24601).

You talk to one model in the OpenCode TUI — ralph-rlm/supervisor. Behind it, a small local helper runs the loop for you: it plans the work with you, starts a fresh worker for each attempt, runs your test command to decide "done," and carries lessons forward between attempts — all in the background. You steer in plain language ("status?", "pause", "the API changed, replan") and review durable files, not an endless chat log.

Why use it

• Set a goal and leave. The loop self-corrects across many attempts without babysitting.
• Your tests are the finish line. A verify.command you choose is the single source of truth for "done" — not vibes.
• Memory you can read, edit, and trust. Progress lives in plain files (PLAN.md, notes, …) you can version and steer.
• Plan before building. A short interview turns a one-line goal into a real plan with a definition of done — before any code is written.

How a run feels

You:   Add JWT auth; the test suite must pass.
Ralph: Let's plan first — refresh tokens too? which test command counts as "done"?
You:   yes, refresh tokens; npm test
Ralph: Plan locked (PLAN.md). Attempt 1 running in the background — ask "status?" anytime.

       …worker implements → verify fails → notes the reason → attempt 2 → verify passes…

You:   status?
Ralph: Done — verify passed on attempt 2. Summary is in CONVERSATION.md.

Quick start

Fastest path — let your agent set it up. From your project, install the setup skill:

npx skills add doeixd/opencode-ralph-rlm

Then paste this to your coding agent:

Use the setup-opencode-ralph-rlm skill to install Ralph RLM in this project.

That's it — the skill inspects the repo, installs the wiring, picks a sensible verify.command, runs diagnostics, and offers to add Ralph guidance to your AGENT.md. Then jump to Start the provider.

Prefer to drive it yourself? The same steps by hand:

1. Install with the agent skill (recommended)

The two commands above are the whole step. The skill handles repo inspection, setup, config review, verify.command, diagnostics, and asks whether to add Ralph guidance to AGENT.md / AGENTS.md.

2. Or use the CLI directly

In your target repo:

npm install -D @doeixd/opencode-ralph-rlm
npx @doeixd/opencode-ralph-rlm setup

This path uses Node/npm; Bun is not required for end users.

This creates conservative project-local wiring:

• .opencode/plugins/ralph-worker.ts
• .opencode/plugins/ralph-session-bridge.ts
• .opencode/plugins/ralph-autostart.ts — auto-starts the provider when OpenCode loads (skip with setup --no-autostart)
• .opencode/ralph.json
• opencode.json provider entry for ralph-rlm/supervisor

Existing managed files are skipped unless you pass --force. Preview changes with:

npx @doeixd/opencode-ralph-rlm setup --dry-run

Manual examples remain in .opencode/opencode.provider.example.json and .opencode/ralph-provider.example.json.

For full setup options, including manual installation, see INSTALLATION.md.

3. Start the provider

After setup, the provider auto-starts when you open OpenCode (via the ralph-autostart plugin) — so you can usually skip this. To run it manually (or if you used --no-autostart / RALPH_AUTOSTART=0):

npx @doeixd/opencode-ralph-rlm serve
# optional: --port 8787 --opencode-url http://127.0.0.1:4096
#           --worktree /path/to/your/repo

Supervisor LLM credentials (provider process). If you've already authenticated a keyed provider in OpenCode (e.g. Google, OpenCode Zen via opencode auth login), the provider auto-detects it — no extra config needed. To force a specific provider/model instead:

export RALPH_SUPERVISOR_API_KEY="..."
export RALPH_SUPERVISOR_MODEL="gpt-5.4-mini"   # + RALPH_SUPERVISOR_BASE_URL for non-OpenAI endpoints

Or .opencode/ralph-provider.json — see .opencode/ralph-provider.example.json. Check what resolved with curl http://127.0.0.1:8787/api/health (supervisor.ready / model / source).

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

npx @doeixd/opencode-ralph-rlm doctor --worktree .
# automated HTTP smoke (provider must be running with RALPH_TEST_MODE=1, or use --spawn):
bun run e2e-smoke -- --spawn

Documentation

Doc	Start here if you want to…
GETTINGSTARTEDGUIDE.md	Set it up and run your first loop (start here)
INSTALLATION.md	Compare install paths (agent skill, CLI, manual)
MIGRATION.md	Upgrade from the v0.1 plugin
CHANGELOG.md	See what changed
DeepWiki	Browse / ask questions about the codebase

The rest of this README is reference material — tools, config, the management API, and how it works under the hood. New here? Follow the getting-started guide instead, or ask DeepWiki anything about the code.

Plan before the loop

A loop is only as good as its PLAN.md — every worker treats it as authority over chat history. The interview-and-create-plan skill turns a vague goal into an authored plan before attempt 1, two ways:

• Path A — supervisor runs it. When you delegate a goal and no authored plan exists, the supervisor enters a planning phase: it explores the repo (repo_search / repo_grep), interviews you to sharpen the goal and stress-test the design, writes PLAN.md via write_plan, agrees a strong verify.command with you (set_verify + run_verify to confirm it fails before the work is done), and only calls start_loop after you approve.
• Path B — run the skill yourself. Run the interview-and-create-plan skill in a normal session (full tools, your chosen model). It writes PLAN.md to the path opencode-ralph-rlm plan-path reports (the active plan dir, not necessarily the repo root). Then switch to ralph-rlm/supervisor and say "go" — start_loop detects the authored plan and launches against it without re-bootstrapping.

Both paths share one source of truth: the skill at skills/interview-and-create-plan/SKILL.md (a repo-local copy overrides the baked-in default). start_loop never overwrites an authored plan, and when it does bootstrap a fresh one it weaves your goal in instead of leaving a placeholder.

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 in the active plan dir (.ralph-rlm/plans/<name>/, or repo root in legacy mode) — not chat history.
• Workers: fresh OpenCode session per attempt; engine spawns via SDK.
• Worker plugin: gates edit/bash until ralph_load_context(); provides FFF-accelerated rlm_grep, rlm_file_search, rlm_glob, and rlm_slice. Its ralph_* / rlm_* tools are hidden from your normal OpenCode sessions — they're denied globally and re-enabled only in the dedicated ralph-worker agent that workers run under.
• Permissions: bash/edit prompts appear in the worker session TUI (answer there).

Protocol files

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

File	Role
PLAN.md	Goal and definition of done
RLM_INSTRUCTIONS.md	Worker playbooks (debug, refactor, repo conventions)
CURRENT_STATE.md	Scratch pad for the active attempt only
PREVIOUS_STATE.md	Snapshot after failed verify
AGENT_CONTEXT_FOR_NEXT_RALPH.md	Handoff: verdict + next-step instructions
NOTES_AND_LEARNINGS.md	Curated durable knowledge — editable, not append-only; link to domain glossary / ADRs / design docs
CONTEXT_FOR_RLM.md	Large reference — workers use rlm_grep + rlm_slice only
SUPERVISOR_LOG.md / CONVERSATION.md	Engine + worker progress feed
.opencode/loop_attempt.json	Attempt marker (worker ralph_ask sync)

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.

Named plans (versions)

Protocol files live in a per-plan directory so you can keep multiple versions and switch between them:

.ralph-rlm/plans/
  default/      PLAN.md  RLM_INSTRUCTIONS.md  NOTES_AND_LEARNINGS.md  …  .state/
  jwt-auth/     …
  refactor-api/ …
  .active       → active plan name

• Layout is set by plans.dir in .opencode/ralph.json (default .ralph-rlm/plans). Set it to "" or "." for the legacy root layout.
• Backward compatible: if a repo already has a root PLAN.md (a pre-named-plans install) and no .ralph-rlm/plans, the legacy root layout is auto-detected and kept.
• Switching: the supervisor exposes list_plans, select_plan <name>, and new_plan <name>. start_loop, read_protocol, and write_plan all target the active plan. The active plan is tracked by the .active pointer (per worktree).
• Config location: ralph.json is read from .ralph-rlm/ralph.json first, then .opencode/ralph.json.
• Markers (loop_attempt.json, pending_input.json) live in each plan's .state/ dir, so plans don't collide.

Default agent instructions

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

Layer	Source	What it defines
Supervisor	packages/provider/server/lib/supervisor-agent.ts	Role boundaries, user-intent → tool routing, communication style
Worker system	packages/engine/src/templates.ts → injected by worker plugin	File-first protocol, one-pass lifecycle, anti-patterns
Worker spawn	templates.workerPrompt	Numbered steps per attempt (ralph_load_context → … → ralph_verify → STOP)
Bootstrap	templates.bootstrapPlan, bootstrapRlmInstructions	Initial PLAN.md + RLM_INSTRUCTIONS.md on start_loop
Rollover	templates.continuePrompt	Next-step block in AGENT_CONTEXT_FOR_NEXT_RALPH.md after failed verify

Customize without forking:

Variable	Overrides
RALPH_WORKER_SYSTEM_PROMPT	Worker system prompt (use @path/to/file for multiline)
RALPH_COMPACTION_CONTEXT	Context injected on session compaction
RALPH_CONTEXT_GATE_ERROR	Message when edit/bash blocked before ralph_load_context()

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.

Tool	Purpose
start_loop	Bootstrap protocol files, begin attempt 1 (launches against an authored PLAN.md when one exists)
repo_search / repo_grep	Planning-phase repo exploration (cross-reference the goal against the code)
write_plan	Write the authored PLAN.md after the planning interview is approved
list_plans / select_plan / new_plan	List, switch, or create named plans (versions) under the configured plans dir
loop_status	Attempt, paused/done/stopped, worker id, last verify
pause_loop / resume_loop / stop_loop	Control background orchestration
peek_worker	Tail of CURRENT_STATE.md
read_protocol	Read allowlisted protocol file
update_plan / update_rlm_instructions	Unified diff patches + changelog
get_verify / set_verify / run_verify	Read / write / dry-run verify.command — craft & validate the loop's stop condition with the user
last_verify_output	Raw verify stdout/stderr
list_worker_questions / answer_worker	Worker ralph_ask queue
spawn_swarm	Parallel side agents (declarative tasks)
swarm_status / swarm_cancel / swarm_collect	Manage swarms
swarm_unsafe_runtime_code_eval	Opt-in SDK script eval (localhost only)

Test mode (no external LLM): RALPH_TEST_MODE=1 npx @doeixd/opencode-ralph-rlm serve --worktree .

Worker tools

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

Tool	Purpose
ralph_load_context	First call every attempt — loads protocol files + agent rules
ralph_report	Progress to SUPERVISOR_LOG.md / CONVERSATION.md
ralph_set_status	running | blocked | done | error
ralph_verify	Run verify.command once; then STOP
rlm_file_search	Fuzzy file search across the worktree
rlm_glob	Fast glob discovery, e.g. **/*.ts
rlm_grep / rlm_slice	Search/slice large files (especially CONTEXT_FOR_RLM.md)
ralph_update_plan / ralph_update_rlm_instructions	Durable strategy patches
ralph_ask	Blocking question to supervisor (use sparingly)

rlm_file_search, rlm_glob, and rlm_grep use optional @ff-labs/fff-node acceleration when it is available. If the native package cannot load or scan, Ralph keeps working: rlm_grep falls back to its exact TypeScript file scan and the discovery tools return a structured unavailable reason.

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 npx @doeixd/opencode-ralph-rlm serve --worktree . running:

Endpoint	Purpose
GET /api/health	Provider + OpenCode connectivity
GET /api/loops	Active loop runs
GET /api/loops/:sessionId	Loop status
POST /api/loops/:sessionId/pause	Pause
POST /api/loops/:sessionId/resume	Resume
POST /api/loops/:sessionId/stop	Stop + abort worker
POST /api/loops/:sessionId/message	Inject an out-of-band message to the supervisor (watchers/scripts)
GET /api/swarms	List swarms (?sessionId=)
POST /api/swarms/:swarmId/cancel	Cancel swarm

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

External messages (watchers)

Scripts and schedulers can send the supervisor a message out-of-band — useful for "watch for X, then tell the supervisor." The message is recorded to the active plan's CONVERSATION.md / SUPERVISOR_LOG.md, shown as a TUI toast, and (by default) runs a supervisor turn so it can act autonomously (pause, replan, spawn a swarm, even start a loop).

# Discover the session id, then send a message
opencode-ralph-rlm sessions
opencode-ralph-rlm send-message -s <sessionId> -m "CI went red — pause and replan."

# Just notify (record + toast), don't run a supervisor turn:
opencode-ralph-rlm send-message -s <sessionId> -m "deploy finished" --no-run --source deploy-bot

Or hit the endpoint directly so any language/cron can drive it:

curl -s http://127.0.0.1:8787/api/loops/<sessionId>/message \
  -H 'content-type: application/json' \
  -d '{"message":"main branch updated — rebase and re-verify","source":"git-hook"}'

A watcher then becomes a small script the agent can write, e.g. PowerShell polling a condition:

while ($true) {
  if (Test-Path .\BUILD_FAILED) {
    opencode-ralph-rlm send-message -s $env:RALPH_SESSION -m "Build failed — stop and diagnose."
    Remove-Item .\BUILD_FAILED
  }
  Start-Sleep -Seconds 30
}

Body fields: message (required), source (label), toast (default true), runTurn (default true; false records + toasts only). The provider is localhost-only by default and the management API is unauthenticated — keep it bound to loopback.

Configuration reference

.opencode/ralph.json

Key	Default	Notes
enabled	true	Master switch
maxAttempts	20	Stop after N failed verify cycles
verify.command	—	Required for real loops
verifyTimeoutMinutes	0	0 = no timeout
heartbeatMinutes	15	Staleness warning threshold
gateDestructiveToolsUntilContextLoaded	true	Worker must call ralph_load_context() first
agentMdPath	—	Static rules file (e.g. AGENT.md)
plans.dir	.ralph-rlm/plans	Base dir for named plans. ""/"." = legacy root layout
plans.active	default	Default active plan name (overridden by the .active pointer)
fff.enabled	true	Optional native search acceleration
fff.scanTimeoutMs	10000	Initial FFF index scan timeout
subAgentEnabled	true	Required for swarms
swarm.enabled	true	Declarative swarms
swarm.maxConcurrent	5	Parallel spawn cap
swarm.unsafeEvalEnabled	false	Script eval gate

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

Environment variables

Variable	Used by
RALPH_SUPERVISOR_API_KEY	Provider supervisor LLM
RALPH_SUPERVISOR_MODEL	Provider supervisor LLM
RALPH_SUPERVISOR_BASE_URL	Provider supervisor LLM
RALPH_OPENCODE_AUTH_PATH	Override path to OpenCode auth.json for supervisor credential auto-detect
OPENCODE_BASE_URL	Engine SDK (default http://127.0.0.1:4096)
RALPH_PROVIDER_PORT	Provider port (default 8787)
RALPH_WORKTREE	Default worktree for opencode-ralph-rlm doctor / serve
RALPH_TEST_MODE	Scripted supervisor (tests / CI / smoke)
RALPH_SESSION_DEBUG	Log session correlation headers on completions
RALPH_ALLOW_ANONYMOUS_SESSION	Opt-in anonymous session key (1) — avoid in production
RALPH_SWARM_UNSAFE_EVAL	Enable unsafe swarm scripts (1)
RALPH_WORKER_SYSTEM_PROMPT	Override worker system prompt
RALPH_COMPACTION_CONTEXT	Override compaction context block
RALPH_CONTEXT_GATE_ERROR	Override context-gate error message
RALPH_FFF_DISABLED	Disable optional FFF worker search acceleration (1)

Architecture (under the hood)

You don't need this to use Ralph — it's here if you want to know what's running.

v0.2 uses a provider-as-supervisor design. The loop is exposed as a custom OpenCode provider model (ralph-rlm/supervisor), so you talk to one session while deterministic code owns verify, rollover, and worker lifecycle behind the API.

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, …)

Layer	Module	Role
Supervisor API	packages/provider	OpenAI-compatible /v1/chat/completions, management /api/*
Loop engine	packages/engine	Verify, rollover, worker spawn, swarms — no LLM orchestration
Worker tools	packages/worker-plugin	RLM tools, context gate, ralph_ask
Session bridge	.opencode/plugins/ralph-session-bridge.ts	Injects x-opencode-session-id on provider requests

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.

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

Monorepo modules: packages/engine, packages/provider, packages/worker-plugin.

CI: .github/workflows/verify.yml

npm package

Published as a single package with subpath exports:

npm install @doeixd/opencode-ralph-rlm

Import	Contents
@doeixd/opencode-ralph-rlm	Legacy v0.1 bundle (dist/ralph-rlm.js)
@doeixd/opencode-ralph-rlm/engine	Loop + swarm engine
@doeixd/opencode-ralph-rlm/worker-plugin	Thin OpenCode worker plugin
@doeixd/opencode-ralph-rlm/provider	Nitro supervisor server entry

Recommended for users: run npx @doeixd/opencode-ralph-rlm setup, then npx @doeixd/opencode-ralph-rlm serve.

Recommended for development: clone this repo and run bun run ralph-serve.

Philosophy

• Fresh worker context each attempt — state in files, not chat history.
• Supervisor never edits repo code — workers