doeixd/opencode-ralph-rlm

setup-opencode-ralph-rlm

Set up Ralph RLM in an existing OpenCode project by installing the package, running the opencode-ralph-rlm setup command, checking generated .opencode config, and verifying the provider/worker loop wiring.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/doeixd/opencode-ralph-rlm --skill setup-opencode-ralph-rlm

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

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

  1. 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.
  1. 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.
  1. 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.

  1. 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"].
  1. 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"].
  1. 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.
  1. 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.

  1. 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.

  1. 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.
  1. 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.