Ralph Loop Plugin for opencode

Ralph Loop runs a self-referential iteration loop inside your current opencode session. It keeps re-sending the same prompt until a completion promise is detected or the max iteration limit is reached.

Features

• Loop in the same session with the same prompt
• Stop by completion promise or max iterations
• Cancel anytime with a command
• Auto-creates command templates in .opencode/command/
• Stores state in .opencode/ralph-loop.local.md

Installation

npm install opencode-plugin-ralph-loop

Add the plugin to your opencode config (project-level example):

{
  "plugin": ["opencode-plugin-ralph-loop"]
}

Commands

/ralph-loop

Start the loop in the current session. The loop submits prompts in the foreground so you can see streaming output. It clears the current prompt input.

/ralph-loop "Your task description" --max-iterations 10 --completion-promise "DONE"

Options:

• --max-iterations N: maximum number of iterations (0 means unlimited)
• --completion-promise TEXT: exact text inside <promise>TEXT</promise>

/cancel-ralph

Cancel the active loop and remove the state file.

/ralph-help

Show Ralph Loop help.

How it works

1. /ralph-loop stores state in .opencode/ralph-loop.local.md
2. The plugin waits for session.idle
3. It checks the last assistant message for <promise>...</promise>
4. If not complete, it increments the iteration and re-sends the same prompt in the active TUI session

State File

The state file uses YAML frontmatter + prompt body:

---
active: true
iteration: 1
max_iterations: 10
completion_promise: "DONE"
started_at: "2026-01-15T00:00:00.000Z"
session_id: "session_..."
---

Your prompt text

Delete the state file or run /cancel-ralph to stop the loop.

Development

npm install
npm run typecheck
npm run build

This project uses typescript-language-server and typescript for LSP support.

License

MIT