Setup OpenCode Ralph RLM

Use this skill to install Ralph RLM into a target repository and make it usable from OpenCode as the

ralph-rlm/supervisor

model.

Workflow

Inspect the target repository.
- Confirm the working directory is the project root.
- Identify the package manager and test command from lockfiles and
```
package.json
```
  scripts.
- Check for existing
```
opencode.json
```
  ,
```
.opencode/ralph.json
```
  , and
```
.opencode/plugins/
```
  .
- If the repo already has OpenCode or Ralph config, read references/config-files.md before editing.
Install the Ralph package if the project can accept a dev dependency.
- Prefer the package manager already used by the repo.
- Package name:
```
@doeixd/opencode-ralph-rlm
```
  .
- If the user only wants a one-time setup, use
```
npx @doeixd/opencode-ralph-rlm setup
```
  instead.
- Do not require Bun for end users; the published CLI is a Node binary.
Run setup from the project root.
bash
```
npx @doeixd/opencode-ralph-rlm setup --worktree .
```
Use
```
--dry-run
```
first when the repo already has OpenCode config. Use
```
--force
```
only when the user explicitly wants generated Ralph files overwritten. See references/cli.md for command flags and expected output.

Review generated files.

.opencode/plugins/ralph-worker.ts

should re-export

@doeixd/opencode-ralph-rlm/worker-plugin

.opencode/plugins/ralph-session-bridge.ts

should inject

x-opencode-session-id

and

directory

```
.opencode/plugins/ralph-autostart.ts
```
starts the provider automatically when OpenCode loads (so the user need not run
```
serve
```
by hand). Skipped if
```
setup --no-autostart
```
was used; disable at runtime with
```
RALPH_AUTOSTART=0
```
.
```
.opencode/ralph.json
```
should have a realistic
```
verify.command
```
.

.opencode/ralph.json

includes

plans: { dir: ".ralph-rlm/plans", active: "default" }

— the named-plan layout. Protocol files (

PLAN.md

RLM_INSTRUCTIONS.md

, …) will live under

.ralph-rlm/plans/<name>/

, not the repo root.

opencode-ralph-rlm plan-path

prints the active plan's

PLAN.md

location.

```
.opencode/ralph.json
```
may include
```
fff.enabled
```
and
```
fff.scanTimeoutMs
```
; leave the defaults unless the project cannot load optional native dependencies.
```
opencode.json
```
should preserve existing providers and include
```
provider["ralph-rlm"]
```
.

Adjust
```
verify.command
```
if auto-detection guessed poorly.
- Bun projects usually use
```
["bun", "run", "test"]
```
  or
```
["bun", "run", "verify"]
```
  .
- npm projects usually use
```
["npm", "test"]
```
  .
- Rust projects usually use
```
["cargo", "test"]
```
  .
- Python projects usually use
```
["python", "-m", "pytest"]
```
  .
Ask whether to add Ralph guidance to the project agent instructions.
- Look for
```
.opencode/ralph.json
```
```
agentMdPath
```
  , then
```
AGENT.md
```
  , then
```
AGENTS.md
```
  .
- Ask the user before creating or editing the guidance file.
- If they agree, append a short Ralph section; use references/agent-guidance.md for wording.
Run diagnostics.
bash
```
npx @doeixd/opencode-ralph-rlm doctor --worktree .
```
A provider warning is expected until the provider is running. For failures, read references/troubleshooting.md.
Set up models — discover what the user already has first; only ask if nothing usable is found.

There are two model decisions:
- Supervisor — the LLM the provider calls for orchestration (planning interview, tool routing, status). Needs reliable function/tool-calling.
- Worker — the model spawned OpenCode sessions use to write code. Workers run through OpenCode, so they already use OpenCode's providers/auth.
Discover existing credentials/models before configuring anything:
- ```
opencode auth list
```
  — which providers are authenticated.
- ```
opencode models
```
  — available model ids (e.g.
```
opencode/deepseek-v4-flash-free
```
  ,
```
anthropic/claude-*
```
  ).
Supervisor: if the user has a keyed provider authenticated in OpenCode (e.g. Google, OpenCode Zen), the provider auto-detects it — no separate key needed. So usually you do nothing here. Only set
```
RALPH_SUPERVISOR_API_KEY
```
(+
```
RALPH_SUPERVISOR_MODEL
```
/
```
RALPH_SUPERVISOR_BASE_URL
```
) or
```
.opencode/ralph-provider.json
```
```
supervisor
```
if the user wants a specific provider/model, or if no keyed provider is authenticated.
Worker: leaving it unset is fine — workers use OpenCode's configured default model. To run coding on a free model, recommend (don't force) setting
```
.opencode/ralph-provider.json
```
```
worker.providerID
```
+
```
worker.modelID
```
to a free OpenCode model such as
```
opencode
```
/
```
deepseek-v4-flash-free
```
. Confirm with the user before writing it.
If nothing usable is found (no authenticated provider, no key): direct the user to authenticate before launching, e.g.:
bash
```
opencode auth login
```
or set
```
RALPH_SUPERVISOR_API_KEY
```
. Do not start the provider expecting the supervisor to work until at least one credential path exists. See references/config-files.md.
Re-open OpenCode — the provider auto-starts; then verify the supervisor is ready.
- With the auto-start plugin installed (default), the provider launches automatically when OpenCode loads — no manual
  serve
  needed. OpenCode loads providers and plugins at startup, so quit and re-open the OpenCode TUI for the
```
ralph-rlm/supervisor
```
  model + plugins to take effect.
- Check readiness:
```
curl http://127.0.0.1:8787/api/health
```
  —
```
supervisor.ready
```
  should be
```
true
```
  (it shows the resolved
```
model
```
  ,
```
source
```
  e.g.
```
opencode-auth:google
```
  , and the provider
```
version
```
  ). If unreachable, the provider may still be starting (give it a moment) or auto-start was disabled — then start it manually:
  bash
```
npx @doeixd/opencode-ralph-rlm serve --worktree .
```
- If you just updated Ralph, restart so the new version loads. The provider is idempotent (one instance per port, reused), and
```
serve
```
  's pre-flight refuses to start a duplicate — if it reports an existing provider of a different version, stop the old one first.
- Then select the ralph-rlm/supervisor
  model.
Suggest planning before the first loop.

A loop is only as good as its
```
PLAN.md
```
. Recommend planning the goal with the supervisor (it runs an interview before
```
start_loop
```
) or via the
```
interview-and-create-plan
```
skill, rather than delegating a one-line goal cold.

Notes

The setup command is intentionally conservative: it skips existing managed files unless
```
--force
```
is passed.
```
npx @doeixd/opencode-ralph-rlm ...
```
is the portable command. The binary installed by the package is named
```
opencode-ralph-rlm
```
.
Worker search uses optional
```
@ff-labs/fff-node
```
acceleration when available. If it is unavailable,
```
rlm_grep
```
falls back automatically; set
```
RALPH_FFF_DISABLED=1
```
only when native search causes local issues.
Node can run some
```
.ts
```
files directly in recent versions, but Node refuses TypeScript files under
```
node_modules
```
; the npm package should ship compiled JavaScript for the CLI.
Do not hand-copy the legacy v0.1 plugin or tell users to call
```
ralph_spawn_worker
```
.
For supervisor LLM credentials, prefer environment variables first:
- ```
RALPH_SUPERVISOR_API_KEY
```
- ```
RALPH_SUPERVISOR_MODEL
```
Use
```
.opencode/ralph-provider.json
```
only when repo-local supervisor/worker defaults are needed.

setup-opencode-ralph-rlm

NPX Install

Tags

SKILL.md Content

Setup OpenCode Ralph RLM

Workflow

Notes