🚀 Socket Launch Week Day 5:Introducing Repository Access Permissions and Custom Roles.Learn more →
Sign In

opencode-ralph-loop

Package Overview
Dependencies
Maintainers
1
Versions
11
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

opencode-ralph-loop - npm Package Compare versions

Comparing version
1.0.1
 to
1.0.2
+34
commands/help.md
---
description: Show Ralph Loop plugin help and available commands
---
# Ralph Loop Help
## Available Commands
- `/ralph-loop <task>` - Start an auto-continuation loop for the given task
- `/cancel-ralph` - Stop an active Ralph Loop
## Quick Start
```
/ralph-loop Build a REST API with user authentication
```
The AI will work on your task and automatically continue until it outputs `<promise>DONE</promise>` to signal completion.
## How It Works
1. Creates state file at `.opencode/ralph-loop.local.md`
2. Works on task until idle
3. If no `<promise>DONE</promise>` found, auto-continues
4. Repeats until complete or max iterations (100) reached
## Cancellation
To stop early:
```
/cancel-ralph
```
For more details, the AI can use the `help` skill.
+66
skills/help/SKILL.md
---
name: help
description: Explain Ralph Loop plugin and available commands
---
# Ralph Loop Help
The Ralph Loop plugin provides auto-continuation for complex tasks in opencode.
## Available Commands
### `/ralph-loop <task>`
Start an iterative development loop that automatically continues until the task is complete.
Example:
```
/ralph-loop Build a REST API with authentication
```
The AI will work on your task and automatically continue until completion.
### `/cancel-ralph`
Cancel an active Ralph Loop before it completes.
Example:
```
/cancel-ralph
```
## How It Works
1. **Start**: `/ralph-loop` creates a state file at `.opencode/ralph-loop.local.md`
2. **Loop**: When the AI goes idle, the plugin checks if `<promise>DONE</promise>` was output
3. **Continue**: If not found, it injects "Continue from where you left off"
4. **Stop**: Loop continues until DONE is found or max iterations (100) reached
5. **Cleanup**: State file is deleted when complete
## Completion Signal
When the task is fully complete, the AI outputs:
```
<promise>DONE</promise>
```
This signals the loop to stop. The AI should ONLY output this when the task is truly complete.
## State File
Located at `.opencode/ralph-loop.local.md` (add to `.gitignore`):
```markdown
---
active: true
iteration: 3
maxIterations: 100
sessionId: ses_abc123
---
Your original task prompt
```
## Credits
- Inspired by [Anthropic's Ralph Wiggum](https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum) plugin for Claude Code
- Standalone extraction from [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode)
+15
-3
commands/cancel-ralph.md

@@ -5,8 +5,20 @@ ---

Cancel the Ralph Loop by removing the state file:
# Cancel Ralph
Cancel the active Ralph Loop.
## Steps
1. Check if a loop is active and get the iteration count:
```bash
rm -f .opencode/ralph-loop.local.md
if [ -f .opencode/ralph-loop.local.md ]; then
grep '^iteration:' .opencode/ralph-loop.local.md
rm -f .opencode/ralph-loop.local.md
echo "Ralph Loop cancelled."
else
echo "No active Ralph Loop to cancel."
fi
```
Confirm to the user: "Ralph Loop cancelled."
2. Report the result to the user.
+19
-5
commands/ralph-loop.md

@@ -5,6 +5,10 @@ ---

Start the Ralph Loop for iterative development.
# Ralph Loop
First, activate the loop by creating the state file in the project directory:
Start an iterative development loop that automatically continues until the task is complete.
## Setup
Create the state file in the project directory:
```bash

@@ -22,8 +26,18 @@ mkdir -p .opencode && cat > .opencode/ralph-loop.local.md << 'EOF'

Then begin working on the user's task: $ARGUMENTS
## Task
When you have FULLY completed the task, signal completion by outputting:
Now begin working on the task: **$ARGUMENTS**
## Completion
When the task is FULLY completed, signal completion by outputting:
```
<promise>DONE</promise>
```
This will stop the auto-continuation loop.
**IMPORTANT:** ONLY output this when the task is COMPLETELY and VERIFIABLY finished. Do NOT output false promises to escape the loop.
## Cancellation
Use `/cancel-ralph` to stop early.
+1
-1
package.json
{
"name": "opencode-ralph-loop",
"version": "1.0.1",
"version": "1.0.2",
"description": "Minimal Ralph Loop plugin for opencode - auto-continues until task completion",

@@ -5,0 +5,0 @@ "main": "src/index.ts",

+30
-7
README.md

@@ -27,2 +27,4 @@ # opencode-ralph-loop

On first run, the plugin will automatically install skills and commands to your `~/.config/opencode/` directory.
## Usage

@@ -44,9 +46,9 @@

### Check status
### Get help
```
/ralph-status
/help
```
### How it works
## How it works

@@ -59,3 +61,3 @@ 1. `/ralph-loop` creates a state file at `.opencode/ralph-loop.local.md`

### Completion
### Completion Promise

@@ -68,3 +70,3 @@ When the AI finishes a task, it outputs:

This signals the loop to stop.
**Important:** The AI should ONLY output this when the task is COMPLETELY and VERIFIABLY finished. False promises are not allowed.

@@ -97,7 +99,28 @@ ## State File

- **Plug-and-play**: Just add to config and restart - no manual setup
- **Minimal**: ~200 lines, no bloat
- **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
- **Tools**: `/ralph-loop`, `/cancel-ralph`, and `/ralph-status`
- **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
```
## Credits

@@ -104,0 +127,0 @@ 

+27
-3
skills/cancel-ralph/SKILL.md

@@ -8,12 +8,36 @@ ---

Stop an active Ralph Loop.
Stop an active Ralph Loop before completion.
## How to Use
When you invoke this skill, delete the state file to deactivate the loop:
When you invoke this skill:
1. First, check if a loop is active:
```bash
test -f .opencode/ralph-loop.local.md && echo "Loop is active" || echo "No active loop"
```
2. If active, read the current iteration count:
```bash
grep '^iteration:' .opencode/ralph-loop.local.md
```
3. Delete the state file to stop the loop:
```bash
rm -f .opencode/ralph-loop.local.md
```
Then inform the user: "Ralph Loop cancelled."
4. Inform the user of the cancellation and which iteration was reached.
## When to Use
Use this command when:
- The task requirements have changed
- You want to restart with different parameters
- The loop appears stuck and you want manual control
- You need to work on something else
Note: Prefer completing tasks properly with `<promise>DONE</promise>` when possible.
+53
-7
skills/ralph-loop/SKILL.md

@@ -10,4 +10,15 @@ ---

## How to Use
## How It Works
The Ralph Loop creates a continuous feedback cycle for completing complex tasks:
1. You work on the task until you go idle
2. The plugin detects the idle state and checks for completion
3. If not complete, it prompts you to continue where you left off
4. This repeats until you output the completion promise or max iterations reached
Your previous work remains accessible through files and git history, enabling progressive refinement across iterations.
## Starting the Loop
When you invoke this skill, create the state file in the project directory:

@@ -22,13 +33,13 @@

---
[The user's task prompt goes here]
EOF
```
Then inform the user:
Then inform the user and begin working on the task.
"Ralph Loop started (max 100 iterations). I will auto-continue until the task is complete. When done, I will output `<promise>DONE</promise>` to signal completion. Use /cancel-ralph to stop early."
## Completion Promise - CRITICAL RULES
## Completion
When you have FULLY completed the task, signal completion by outputting:
When you have fully completed the task, output:
```

@@ -38,2 +49,37 @@ <promise>DONE</promise>

This signals the loop to stop.
**IMPORTANT CONSTRAINTS:**
- ONLY output `<promise>DONE</promise>` when the task is COMPLETELY and VERIFIABLY finished
- The statement MUST be completely and unequivocally TRUE
- Do NOT output false promises to escape the loop, even if you think you're stuck
- Do NOT lie even if you think you should exit for other reasons
- If you're blocked, explain the blocker and request help instead of falsely completing
The loop can only be stopped by:
1. Truthful completion promise
2. Max iterations reached
3. User running `/cancel-ralph`
## Checking Status
Check current iteration:
```bash
grep '^iteration:' .opencode/ralph-loop.local.md
```
## State File Format
The state file at `.opencode/ralph-loop.local.md` uses YAML frontmatter:
```markdown
---
active: true
iteration: 3
maxIterations: 100
sessionId: ses_abc123
---
Your original task prompt
```
Add `.opencode/ralph-loop.local.md` to your `.gitignore`.
+85
-11
src/index.ts

@@ -1,3 +0,4 @@

import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync, readdirSync } from "fs";
import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync, readdirSync, cpSync } from "fs";
import { dirname, join } from "path";
import { fileURLToPath } from "url";

@@ -16,4 +17,64 @@ // Types

const MESSAGE_DIR = join(process.env.HOME || "~", ".local/share/opencode/storage/message");
const OPENCODE_CONFIG_DIR = join(process.env.HOME || "~", ".config/opencode");
const COMPLETION_TAG = /<promise>\s*DONE\s*<\/promise>/is;
// Get plugin root directory
function getPluginRoot(): string {
try {
// ESM: use import.meta.url
const __filename = fileURLToPath(import.meta.url);
return dirname(dirname(__filename)); // Go up from src/ to plugin root
} catch {
// Fallback for CJS
return dirname(__dirname);
}
}
// Auto-copy skills and commands to opencode config on first run
function setupSkillsAndCommands(): void {
const pluginRoot = getPluginRoot();
const skillsDir = join(OPENCODE_CONFIG_DIR, "skill");
const commandsDir = join(OPENCODE_CONFIG_DIR, "command");
// Copy skills
const pluginSkillsDir = join(pluginRoot, "skills");
if (existsSync(pluginSkillsDir)) {
const skills = ["ralph-loop", "cancel-ralph", "help"];
for (const skill of skills) {
const srcSkillDir = join(pluginSkillsDir, skill);
const destSkillDir = join(skillsDir, skill);
if (existsSync(srcSkillDir) && !existsSync(destSkillDir)) {
try {
mkdirSync(destSkillDir, { recursive: true });
cpSync(srcSkillDir, destSkillDir, { recursive: true });
console.log(`[ralph-loop] Installed skill: ${skill}`);
} catch (e) {
console.error(`[ralph-loop] Failed to install skill ${skill}:`, e);
}
}
}
}
// Copy commands
const pluginCommandsDir = join(pluginRoot, "commands");
if (existsSync(pluginCommandsDir)) {
const commands = ["ralph-loop.md", "cancel-ralph.md", "help.md"];
for (const cmd of commands) {
const srcCmd = join(pluginCommandsDir, cmd);
const destCmd = join(commandsDir, cmd);
if (existsSync(srcCmd) && !existsSync(destCmd)) {
try {
mkdirSync(commandsDir, { recursive: true });
cpSync(srcCmd, destCmd);
console.log(`[ralph-loop] Installed command: ${cmd}`);
} catch (e) {
console.error(`[ralph-loop] Failed to install command ${cmd}:`, e);
}
}
}
}
}
// Get state file path (project-relative)

@@ -120,4 +181,7 @@ function getStateFile(directory: string): string {

// Auto-setup skills and commands on first run
setupSkillsAndCommands();
return {
// Register tools (slash commands)
// Register tools (fallback if skills/commands not available)
tool: {

@@ -176,4 +240,4 @@ "ralph-loop": {

"ralph-status": {
description: "Check Ralph Loop status",
"help": {
description: "Show Ralph Loop plugin help",
parameters: {

@@ -184,9 +248,19 @@ type: "object",

async execute() {
const state = readState(directory);
if (!state.active) {
return "No active Ralph Loop.";
}
return `Ralph Loop active:
- Iteration: ${state.iteration}/${state.maxIterations}
- Task: ${state.prompt || "(no prompt)"}`;
return `# Ralph Loop Help
## Available Commands
- \`/ralph-loop <task>\` - Start an auto-continuation loop
- \`/cancel-ralph\` - Stop an active loop
## How It Works
1. Start with: /ralph-loop "Build a REST API"
2. AI works on the task until idle
3. Plugin auto-continues if not complete
4. Loop stops when AI outputs: <promise>DONE</promise>
## State File
Located at: .opencode/ralph-loop.local.md`;
}

@@ -193,0 +267,0 @@ }