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

npm install @suryanshu-09/ralph_codes

Or with yarn:

yarn add @suryanshu-09/ralph_codes

Quick Start

Automatic Mode (Recommended)

// 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:

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

Orchestrated Mode

// 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

Task Execution Layers

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)

Why Fresh Sessions?

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

ralph_auto

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

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)

ralph_start

Initialize a manual Ralph loop for orchestrated control.

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

ralph_add_tasks

Add atomic tasks with explicit dependencies.

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

ralph_run

Execute all pending tasks with automatic parallelization.

await ralph_run({})

ralph_status

Check the current state of an active loop.

await ralph_status({})

ralph_help

Display help information.

await ralph_help({})

Examples

Example 1: Building a REST API

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

Example 2: Complex Multi-Step Project

// 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({})

Example 3: Refactoring Legacy Code

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({})

Example 4: Data Pipeline

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

Best Practices

Writing Good Task Descriptions

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"

Managing Dependencies

• 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

Model Selection

• Use fast, cheap models for simple tasks
• Use capable models for complex reasoning tasks
• Specify models when consistency matters:

  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 https://www.gnu.org/licenses/.

Built for OpenCode AI.

Third-Party Notices

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