Ralph - Autonomous Agent for OpenCode

Ralph is a single-shot autonomous agent for OpenCode that breaks complex tasks into small, verifiable iterations.

What It Does

Instead of trying to complete a big task in one shot (which often leads to context bloat and mistakes), Ralph:

1. Does one small unit of work - creates a few files, fixes one error, adds one feature
2. Commits progress - meaningful git commits after each step
3. Updates state - tracks what's done, what's remaining, any blockers
4. Exits - outputs a "promise" of current status
5. Gets re-invoked - the plugin creates a fresh session and continues

This loop repeats until the task is DONE or BLOCKED. Each iteration has fresh context, so Ralph can handle tasks that would normally exceed context limits.

Example

/ralph add user authentication with email/password --auto

Ralph might:

• Iteration 1: Create user model and migration
• Iteration 2: Add registration endpoint
• Iteration 3: Add login endpoint
• Iteration 4: Add middleware for protected routes
• Iteration 5: Write tests
• Iteration 6: Run tests, fix failures
• Iteration 7: Verify everything works, mark DONE

Installation

Copy the files to your OpenCode config directory:

# Create directories if they don't exist
mkdir -p ~/.config/opencode/plugin
mkdir -p ~/.config/opencode/command

# Copy files
cp plugin/ralph-auto-loop.ts ~/.config/opencode/plugin/
cp command/ralph.md ~/.config/opencode/command/
cp command/ralph-reset.md ~/.config/opencode/command/

# Copy package.json (or merge if you have existing dependencies)
cp package.json ~/.config/opencode/

# Install dependencies
cd ~/.config/opencode && npm install
# or: bun install / pnpm install

Restart OpenCode after installation.

Usage

/ralph <goal>              Run one iteration
/ralph <goal> --auto       Auto-loop until done or blocked
/ralph <goal> --max 20     Set max iterations (default: 10, cap: 50)
/ralph <goal> --dry-run    Plan only, no file changes
/ralph <goal> --strict     Avoid destructive commands

/ralph-reset               Clear state and start fresh

How It Works

1. Each /ralph invocation does ONE unit of work, then stops
2. State is persisted in .ralph-state.json in your project
3. In --auto mode, the plugin detects when Ralph finishes and re-invokes with fresh context
4. Loop continues until status is DONE or BLOCKED

Files

File	Purpose
plugin/ralph-auto-loop.ts	Plugin that handles auto-loop and session management
command/ralph.md	Main Ralph command with all the prompting
command/ralph-reset.md	Helper to clear Ralph state
package.json	Dependencies (@opencode-ai/plugin)

Cancellation

• Ctrl+C during an iteration
• Edit .ralph-state.json and set "auto": false
• Run /ralph-reset to clear all state