Ralph Wiggum Plugin for OpenCode AI

A multi-session task runner with automatic parallelization for OpenCode AI. Breaks down complex prompts into atomic tasks and executes them in parallel using fresh sessions.

Features

- Automatic Task Decomposition: Breaks complex prompts into atomic, independent tasks
- Smart Parallelization: Executes independent tasks concurrently for faster completion
- Fresh Sessions: Each task runs in its own session, preventing context pollution
- Dependency Management: Automatically analyzes and respects task dependencies
- Two Modes: Fire-and-forget automation or orchestrated manual control

Requirements

- Node.js 18.0 or higher
- npm or yarn
- OpenCode AI plugin framework (@opencode-ai/plugin >= 1.0.0)

Installation

``bash
npm install @suryanshu-09/ralph_codes
`

Or with yarn:

`bash
yarn add @suryanshu-09/ralph_codes
`

Quick Start

$3

`typescript
// Just describe what you want, and Ralph handles the rest
await ralph_auto({ prompt: "Build a REST API for a todo app with Express and SQLite" })
`

With custom model:

`typescript
await ralph_auto({
prompt: "Create a Node.js CLI tool for file encryption",
model: "anthropic/claude-opus-4-5-20250929"
})
`

$3

`typescript
// Start with a complex prompt
await ralph_start({ prompt: "Build a real-time chat application" })

// Add detailed tasks
await ralph_add_tasks({
tasks: [
{ id: "setup", content: "Initialize project with TypeScript", dependencies: [] },
{ id: "server", content: "Create WebSocket server", dependencies: ["setup"] },
{ id: "client", content: "Build React frontend", dependencies: ["setup"] },
{ id: "tests", content: "Write integration tests", dependencies: ["server", "client"] }
]
})

// Execute with parallelization
await ralph_run({})
`

How It Works

$3

Ralph organizes tasks into "layers" based on dependencies. Tasks in the same layer can run in parallel:

`
Layer 1 (PARALLEL): database setup
Layer 2 (PARALLEL): auth implementation, API endpoints
Layer 3 (SEQUENTIAL): frontend integration (waits for API)
Layer 4 (SEQUENTIAL): tests (waits for everything)
`

$3

1. Context Isolation: Each task gets a clean context window
2. Failure Isolation: One failed task doesn't corrupt others
3. Atomic Focus: Workers can't wander into other tasks
4. Parallel Speed: True parallel execution across sessions

Tools Reference

$3

Fully automatic task breakdown and execution. Perfect for fire-and-forget usage.

`typescript
await ralph_auto({ prompt: "Create a Node.js CLI tool for file encryption" })
await ralph_auto({
prompt: "Implement user authentication with JWT tokens and refresh tokens",
model: "anthropic/claude-opus-4-5-20250929"
})
`

Arguments:
- prompt (required): The complex task to execute
- model (optional): Override the model (format: provider/model)

$3

Initialize a manual Ralph loop for orchestrated control.

`typescript
await ralph_start({ prompt: "Build a complete SaaS application" })
await ralph_start({
prompt: "Refactor the entire backend",
model: "openai/gpt-4"
})
`

Arguments:
- prompt (required): The task prompt
- model (optional): Model for worker sessions

$3

Add atomic tasks with explicit dependencies.

`typescript
await ralph_add_tasks({
tasks: [
{
id: "setup",
content: "Initialize npm project and install dependencies",
dependencies: []
},
{
id: "models",
content: "Create database models for User and Post",
dependencies: ["setup"]
},
{
id: "routes",
content: "Implement CRUD API routes for posts",
dependencies: ["models"]
}
]
})
`

Arguments:
- tasks (required): Array of task objects with:
- id: Unique identifier
- content: Task description
- dependencies: Array of task IDs this depends on

$3

Execute all pending tasks with automatic parallelization.

`typescript
await ralph_run({})
`

$3

Check the current state of an active loop.

`typescript
await ralph_status({})
`

$3

Display help information.

`typescript
await ralph_help({})
`

Examples

$3

`typescript
await ralph_auto({ prompt: "Create a REST API for a blog with Express.js, SQLite, and JWT auth" })
`

Ralph will:
1. Plan the task breakdown
2. Create tasks for database setup, models, routes, auth, etc.
3. Execute independent tasks in parallel
4. Handle sequential dependencies
5. Return a summary of all sessions and results

$3

`typescript
// Start with a complex prompt
await ralph_start({ prompt: "Build a real-time chat application" })

// Add detailed tasks
await ralph_add_tasks({
tasks: [
{ id: "project_setup", content: "Initialize project with TypeScript and dependencies", dependencies: [] },
{ id: "websocket_server", content: "Set up WebSocket server with Socket.io", dependencies: ["project_setup"] },
{ id: "database_schema", content: "Design and create SQLite schema for users and messages", dependencies: ["project_setup"] },
{ id: "user_auth", content: "Implement user registration and login with JWT", dependencies: ["database_schema"] },
{ id: "chat_rooms", content: "Create chat room management functionality", dependencies: ["websocket_server", "database_schema"] },
{ id: "message_api", content: "Build REST API for message history", dependencies: ["database_schema"] },
{ id: "react_frontend", content: "Create React frontend with chat UI", dependencies: ["websocket_server", "message_api"] },
{ id: "e2e_tests", content: "Write end-to-end tests with Playwright", dependencies: ["user_auth", "chat_rooms", "react_frontend"] }
]
})

// Execute with parallelization
await ralph_run({})
`

$3

`typescript
await ralph_start({ prompt: "Refactor the authentication module to use TypeScript and decorators" })

// Define refactoring tasks
await ralph_add_tasks({
tasks: [
{ id: "types", content: "Create TypeScript type definitions for User, Session, and AuthResult", dependencies: [] },
{ id: "decorators", content: "Implement TypeScript decorators for route protection", dependencies: ["types"] },
{ id: "auth_service", content: "Refactor AuthService to use new types and decorators", dependencies: ["types", "decorators"] },
{ id: "middleware", content: "Create authentication middleware with proper error handling", dependencies: ["auth_service"] },
{ id: "routes", content: "Update all auth routes to use new middleware", dependencies: ["middleware"] },
{ id: "tests", content: "Add unit tests for AuthService with 90% coverage", dependencies: ["auth_service"] }
]
})

await ralph_run({})
`

$3

`typescript
await ralph_auto({ prompt: "Build an ETL pipeline that extracts data from CSV files, transforms it, and loads into PostgreSQL" })
`

Best Practices

$3

Bad:
`
"Implement the backend"
"Create the UI"
`

Good:
`
"Create User model with fields: id, email, password_hash, created_at"
"Implement POST /api/auth/login endpoint that validates credentials and returns JWT"
"Create LoginForm component with email and password inputs with validation"
`

$3

- Tasks with no dependencies run in parallel
- Tasks with dependencies wait for their dependencies to complete
- Keep the dependency tree shallow for better parallelization
- Use explicit dependencies rather than relying on auto-detection

$3

- Use fast, cheap models for simple tasks
- Use capable models for complex reasoning tasks
- Specify models when consistency matters:
`typescript
await ralph_start({
prompt: "Complex refactoring",
model: "anthropic/claude-opus-4-5-20250929"
})
`

Architecture

`
┌─────────────────────────────────────────────────────┐
│ Ralph Wiggum │
├─────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────┐ │
│ │ Task │───>│ Dependency │───>│ Layer │ │
│ │ Decomposer │ │ Analyzer │ │ Builder │ │
│ └─────────────┘ └─────────────┘ └────┬────┘ │
│ │ │
│ ┌─────────────────────────────────────────▼──────┐│
│ │ Execution Engine ││
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ││
│ │ │ Session │ │ Session │ │ Session │ ... ││
│ │ │ #1 │ │ #2 │ │ #3 │ ││
│ │ └────┬────┘ └────┬────┘ └────┬────┘ ││
│ │ │ Parallel │ │ ││
│ └───────┼───────────┼────────────┼──────────────┘│
│ │ │ │ │
│ └───────────┴────────────┘ │
│ Results │
└─────────────────────────────────────────────────────┘
``

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see .

Built for OpenCode AI.

---

Third-Party Notices

This project is based on the Ralph technique by Geoff Huntley.