Multi-session task runner with automatic parallelization for OpenCode AI
npm install @suryanshu-09/ralph_codesA 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.
- 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
- Node.js 18.0 or higher
- npm or yarn
- OpenCode AI plugin framework (@opencode-ai/plugin >= 1.0.0)
``bash`
npm install @suryanshu-09/ralph_codes
Or with yarn:
`bash`
yarn add @suryanshu-09/ralph_codes
`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"
})
`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({})
`
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)
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
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 executemodel
- (optional): Override the model (format: provider/model)
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 promptmodel
- (optional): Model for worker sessions
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 identifiercontent
- : Task descriptiondependencies
- : Array of task IDs this depends on
Execute all pending tasks with automatic parallelization.
`typescript`
await ralph_run({})
Check the current state of an active loop.
`typescript`
await ralph_status({})
Display help information.
`typescript`
await ralph_help({})
`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
`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({})
`
`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({})
`
`typescript`
await ralph_auto({ prompt: "Build an ETL pipeline that extracts data from CSV files, transforms it, and loads into PostgreSQL" })
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"
- 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
- 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"
})
```
┌─────────────────────────────────────────────────────┐
│ Ralph Wiggum │
├─────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────┐ │
│ │ Task │───>│ Dependency │───>│ Layer │ │
│ │ Decomposer │ │ Analyzer │ │ Builder │ │
│ └─────────────┘ └─────────────┘ └────┬────┘ │
│ │ │
│ ┌─────────────────────────────────────────▼──────┐│
│ │ Execution Engine ││
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ││
│ │ │ Session │ │ Session │ │ Session │ ... ││
│ │ │ #1 │ │ #2 │ │ #3 │ ││
│ │ └────┬────┘ └────┬────┘ └────┬────┘ ││
│ │ │ Parallel │ │ ││
│ └───────┼───────────┼────────────┼──────────────┘│
│ │ │ │ │
│ └───────────┴────────────┘ │
│ Results │
└─────────────────────────────────────────────────────┘
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request
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.
---
This project is based on the Ralph technique by Geoff Huntley.