Ralph Loop plugin for opencode
npm install opencode-plugin-ralph-loopRalph 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.
- 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
``bash`
npm install opencode-plugin-ralph-loop
Add the plugin to your opencode config (project-level example):
`json`
{
"plugin": ["opencode-plugin-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
Cancel the active loop and remove the state file.
Show Ralph Loop help.
1. /ralph-loop stores state in .opencode/ralph-loop.local.md
2. The plugin waits for
3. It checks the last assistant message for
4. If not complete, it increments the iteration and re-sends the same prompt in the active TUI session
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.
`bash`
npm install
npm run typecheck
npm run build
This project uses typescript-language-server and typescript` for LSP support.
MIT