Ralph Orchestra

A multi-agent autonomous development framework that coordinates multiple AI CLI agents to work together on software development tasks.

What is Ralph Orchestra?

Ralph Orchestra enables autonomous software development by coordinating specialized AI agents, subagents, and skills together with a Watchdog process for Agent state, context window, and messaging coordination. The agents communicate through shared state files and can run indefinitely until all tasks are complete.

Key Features

• Multi-CLI Support - Works with Claude CLI, OpenCode CLI, and easily extensible to more
• PRD Starter Wizard - AI guided project initialization and configuration
• Multi-Agent Coordination - PM, Developer, Tech Artist, QA, and Game Designer agents with modular skills
• Three Orchestration Modes - Event-driven, Sequential, or HITL
• Watchdog Process - Never-exit orchestrator that manages agent lifecycle
• Message-Based Communication - File-based messages for agent coordination
• Scale-Adaptive Planning - PM adjusts approach based on PRD task count
• Skill Improvement - Agents research and propose skill updates during retrospectives

Quick Start

Prerequisites

Choose your CLI:

• Claude CLI: Install Claude CLI and authenticate
• OpenCode CLI: Install OpenCode and configure a provider

System requirements:

• PowerShell 5.1+ (Windows) or Bash (Linux/macOS)
• Python 3.8+

CLI Provider Selection

Ralph Orchestra supports multiple AI CLIs. Select your provider via:

Option 1: Environment Variable

$env:RALPH_CLI_PROVIDER = "opencode"  # or "claude"

Option 2: Configuration File

Create cli-provider.json in your project root:

{
  "provider": "opencode"
}

Option 3: Command Line

.\.claude\scripts\ralph-event-session.ps1 -Provider opencode

OpenCode Setup

When using OpenCode, create the configuration file:

copy opencode.example.json opencode.json

Then configure your AI provider in opencode.json.

Running Agents

Event-Driven Mode (Recommended)

# With Claude (default)
.\.claude\scripts\ralph-event-session.ps1

# With OpenCode
.\.claude\scripts\ralph-event-session.ps1 -Provider opencode

Sequential Mode (Token-Efficient)

.\.claude\scripts\ralph-single-session.ps1

HITL Mode (Learning)

/ralph-hitl

CLI Provider Architecture

Ralph uses a class-based provider system with PowerShell modules:

.claude/providers/
├── CliProvider.psm1            # Module with base class + helpers
├── ClaudeProvider.ps1          # Claude implementation
├── OpenCodeProvider.ps1        # OpenCode implementation
└── ProviderFactory.ps1         # Factory + registration

Provider Module System

Providers use PowerShell modules (.psm1) for proper class inheritance:

• using module .\CliProvider.psm1 loads the base class at parse time
• This eliminates TypeNotFound warnings from sourced scripts

Provider Differences

Feature	Claude	OpenCode
Agent Selection	--agent in slash command	--agent ralph-{name} flag
Message Delivery	CLI --message argument	Positional argument after flags
MCP Config	--mcp-config CLI arg	Auto-loaded from opencode.json
Agent Definitions	.claude/commands/*.md	.opencode/agents/*.md
Skills Location	.claude/skills/	.claude/skills/ (shared)

Adding New Providers

1. Create NewProvider.ps1 inheriting from CliProvider
2. Add using module .\CliProvider.psm1 at the top
3. Implement required methods (BuildAgentCommand, GetCapabilities, etc.)
4. Register in ProviderFactory.ps1

See Extending for details.

Documentation

Document	Description
Getting Started	Installation, prerequisites, first run
Orchestration Modes	All modes explained in detail
Architecture	System architecture, agent roles, message flow
Configuration	PRD format, agent settings, CLI providers
Extending	Adding custom agents, skills, CLI providers
Monitoring	Dashboard, logs, troubleshooting