使用方法
- 复制安装命令,在自己的智能体环境安装前先检查源码包。
- 从原始文档核对所需工具、凭据和支持的宿主。
- 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/doeixd/opencode-ralph-rlm --skill setup-opencode-ralph-rlm开始前需了解
- 安装不包含模型订阅、API 额度或访问文件的权限。
- 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。
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.jsonscripts. - 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 setupinstead. - Do not require Bun for end users; the published CLI is a Node binary.
- Run setup from the project root.
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.tsshould re-export@doeixd/opencode-ralph-rlm/worker-plugin..opencode/plugins/ralph-session-bridge.tsshould injectx-opencode-session-idanddirectory..opencode/plugins/ralph-autostart.tsstarts the provider automatically when OpenCode loads (so the user need not runserveby hand). Skipped ifsetup --no-autostartwas used; disable at runtime withRALPH_AUTOSTART=0..opencode/ralph.jsonshould have a realisticverify.command..opencode/ralph.jsonincludesplans: { 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-pathprints the active plan'sPLAN.mdlocation..opencode/ralph.jsonmay includefff.enabledandfff.scanTimeoutMs; leave the defaults unless the project cannot load optional native dependencies.opencode.jsonshould preserve existing providers and includeprovider["ralph-rlm"].
- Adjust
verify.commandif 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.jsonagentMdPath, thenAGENT.md, thenAGENTS.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.
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.:
opencode auth loginor 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/supervisormodel + plugins to take effect. - Check readiness:
curl http://127.0.0.1:8787/api/health—supervisor.readyshould betrue(it shows the resolvedmodel,sourcee.g.opencode-auth:google, and the providerversion). If unreachable, the provider may still be starting (give it a moment) or auto-start was disabled — then start it manually:
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 beforestart_loop) or via theinterview-and-create-planskill, rather than delegating a one-line goal cold.
Notes
- The setup command is intentionally conservative: it skips existing managed files unless
--forceis passed. npx @doeixd/opencode-ralph-rlm ...is the portable command. The binary installed by the package is namedopencode-ralph-rlm.- Worker search uses optional
@ff-labs/fff-nodeacceleration when available. If it is unavailable,rlm_grepfalls back automatically; setRALPH_FFF_DISABLED=1only when native search causes local issues. - Node can run some
.tsfiles directly in recent versions, but Node refuses TypeScript files undernode_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_KEYRALPH_SUPERVISOR_MODEL- Use
.opencode/ralph-provider.jsononly when repo-local supervisor/worker defaults are needed.