- TypeScript 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
2ef2386cd9* fix(commands): self-register slash commands via config hook (1.0.10) Slash commands were silently broken on current opencode: the auto-copy shipped them to ~/.config/opencode/command/ (singular), but opencode reads from .../commands/ (plural). `/ralph-loop` etc. never appeared in autocomplete unless the user manually copied the files. Switch to opencode's supported pattern for plugin-defined commands: mutate `input.command` from the `config` hook. opencode merges the plugin-provided dict into the runtime config, so the slash commands appear with zero filesystem state and no path conventions to drift. - New `config` hook adds `ralph-loop`, `cancel-ralph`, `help` defaults. User-defined entries in opencode.json take precedence (we only set when absent). - `setupSkillsAndCommands` renamed to `setupSkills` (commands no longer copied to disk). - Skills target dir corrected from `skill/` (singular, dead) to `skills/` (plural, what opencode actually scans). - commands/*.md files retained in the package for now — they're the same content as the inline templates, useful as documentation. Tests: 24 passing, typecheck clean. Loader-safe: 3 function exports (default, parseState, serializeState); RALPH_COMMANDS is module-internal. * refactor(commands): extract RALPH_COMMANDS + STATE_FILENAME to sibling module - Move RALPH_COMMANDS (non-function const) out of src/index.ts into src/commands.ts. Keeps the plugin entrypoint loader-safe. - Derive setupSkills() skill list from Object.keys(RALPH_COMMANDS) so adding a new command auto-includes its skill directory. - Replace hardcoded .opencode/ralph-loop.local.md paths in templates with STATE_DIR/STATE_FILENAME-derived STATE_PATH. Addresses Gemini review comments on #17 (lines 44, 64, 72). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com> |
||
| .github | ||
| commands | ||
| skills | ||
| src | ||
| tests | ||
| .gitignore | ||
| AGENTS.md | ||
| CLAUDE.md | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| tsconfig.json | ||
| vitest.config.ts | ||
opencode-ralph-loop
Minimal Ralph Loop plugin for opencode - auto-continues until task completion.
Inspired by Anthropic's Ralph Wiggum technique for iterative, self-referential AI development loops.
Why this plugin?
oh-my-opencode is a fantastic, feature-rich plugin that includes Ralph Loop along with many other powerful capabilities like the Sisyphus orchestrator, background agents, and more.
However, we personally found the full suite a bit heavy for our workflow. We also noticed others in the community expressing interest in specific features without needing the complete package. So we extracted just the Ralph Loop functionality into this standalone, lightweight plugin.
If you want the full-featured experience, definitely check out oh-my-opencode. If you just want auto-continuation loops with minimal overhead, this plugin is for you.
Installation
Add to your ~/.config/opencode/opencode.json:
{
"plugin": ["opencode-ralph-loop"]
}
Restart opencode. That's it!
On first run, the plugin will automatically install skills and commands to your ~/.config/opencode/ directory.
Usage
Start a loop
/ralph-loop "Build a REST API with authentication"
The AI will work on your task and automatically continue until completion.
Cancel a loop
/cancel-ralph
Get help
/help
How it works
/ralph-loopcreates a state file at.opencode/ralph-loop.local.md- When the AI goes idle, the plugin checks if
<promise>DONE</promise>was output - If not found, it injects "Continue from where you left off"
- Loop continues until DONE is found or max iterations (100) reached
- State file is deleted when complete
Completion Promise
When the AI finishes a task, it outputs:
<promise>DONE</promise>
Important: The AI should ONLY output this when the task is COMPLETELY and VERIFIABLY finished. False promises are not allowed.
State File
The loop state is stored in your project directory:
.opencode/ralph-loop.local.md
Format (markdown with YAML frontmatter):
---
active: true
iteration: 3
maxIterations: 100
sessionId: ses_abc123
---
Your original task prompt
Add .opencode/ralph-loop.local.md to your .gitignore.
Features
- Plug-and-play: Just add to config and restart - no manual setup
- Auto-setup: Skills and commands are automatically installed on first run
- Minimal: ~300 lines, no bloat
- Project-relative: State file in
.opencode/, not global - Completion detection: Scans session messages for DONE promise
- Progressive context: Skills provide context only when needed
- Commands:
/ralph-loop,/cancel-ralph, and/help
Architecture
Following Anthropic's Claude Code plugin pattern:
opencode-ralph-loop/
├── src/
│ └── index.ts # Main plugin with event hooks and tools
├── skills/
│ ├── ralph-loop/ # Progressive context for starting loops
│ ├── cancel-ralph/ # Context for cancellation
│ └── help/ # Plugin documentation
├── commands/
│ ├── ralph-loop.md # Slash command for starting
│ ├── cancel-ralph.md # Slash command for cancelling
│ └── help.md # Slash command for help
└── package.json
Contributing
PRs welcome. See CONTRIBUTING.md.
Releases
Auto-published from CI with npm provenance via OIDC trusted publishing — each tarball is cryptographically linked to the exact commit, no long-lived tokens involved.
Credits
- Inspired by Anthropic's Ralph Wiggum plugin for Claude Code
- Implementation pattern from oh-my-opencode
License
MIT