A server-based AI development orchestrator powered by the "Ralph Wiggum technique" - run the same AI prompt repeatedly until tasks are complete, with git-backed branching for exploration and structured review at commit boundaries.
Ralph consists of three main components:
A TypeScript server that uses the Claude Code SDK to implement plans using the Ralph Wiggum methodology.
Location: src/server.ts
Features:
- HTTP API for plan execution
- Session management with persistent state
- Git-based branching and checkpointing
- Real-time status updates
API Endpoints:
POST /execute- Start plan executionGET /status/:sessionId- Check execution statusGET /plans- List available plansGET /plans/:planId- Get plan detailsGET /sessions- List active sessionsGET /health- Health check
Usage:
# Build the project
npm run build
# Start the server
npm run server
# CLI mode
ralph run [plan]
# Server mode
ralph server --port 3001A Claude Code skill that generates structured implementation plans from requirements.
Location: skills/ralph-plan-generator.skill.ts (re-exports from src/plan-generator.ts)
Features:
- Parses requirements into structured tasks
- Auto-generates task IDs and dependencies
- Validates plan structure
- Supports markdown export/import
Usage:
Use the ralph-plan-generator skill to create an implementation plan from your requirements.
A Claude Code skill that sends plans to the Ralph server for execution.
Location: .claude/skills/ralph-executor/ralph-executor.skill.ts (contains server client logic)
Features:
- Submits plans to Ralph server
- Tracks execution progress
- Retrieves task results
- Handles errors and retries
Usage:
Use the ralph-executor skill to send a plan to the server and monitor execution.
- Node.js 18+
- npm or yarn
- Git
- Claude Code CLI (for task execution)
# Clone the repository
git clone https://github.com/yourusername/ralph.git
cd ralph
# Install dependencies
npm install
# Build the project
npm run build# Development mode (watch mode)
npm run watch
# Build for production
npm run build
# Start server
npm run server
# Or start CLI mode
npm start-
Generate a Plan:
- In Claude Code, invoke the
ralph-plan-generatorskill - Provide your requirements
- Review and edit the generated plan
- In Claude Code, invoke the
-
Execute the Plan:
- Invoke the
ralph-executorskill - Select your plan
- Monitor execution progress
- Invoke the
ralph/
├── src/ # Main source code
│ ├── types/ # TypeScript type definitions
│ │ └── index.ts
│ ├── plan-generator.ts # Plan parsing and validation
│ ├── executor.ts # Core execution logic
│ ├── server.ts # HTTP API server
│ └── cli.ts # CLI entry point
├── skills/ # Claude Code skills
│ └── ralph-plan-generator.skill.ts
├── .claude/skills/ # Internal skills
│ └── ralph-executor/ # Server client skill
├── plans/ # Generated plans
├── dist/ # Compiled output
├── tsconfig.json
└── package.json
- Language: TypeScript 5.x
- AI SDK: @anthropic-ai/claude-agent-sdk v0.2.8
- Server: Express 5.2.1
- Git: simple-git v3.22.0
- Testing: Vitest v4.0.17
Server configuration can be set via CLI flags:
ralph server --port 3001 --host localhost# Run a plan
ralph run [plan-path]
# List available plans
ralph list
# Show execution status
ralph status
# Start server mode
ralph server [options]The core philosophy: run the same AI prompt repeatedly until tasks are complete, with git-backed branching for exploration and structured review at commit boundaries.
- Planning - Generate structured implementation plans
- Execution - Execute tasks one at a time with AI
- Review - Review changes at commit boundaries
- Iteration - Iterate or fork as needed
- Structured, autonomous AI-driven development
- Git-backed safety with easy rollbacks
- Parallel exploration through branching
- Clear audit trail of all changes
- CLAUDE.md - Detailed project instructions for Claude Code
- ralph-wiggum-technique.md - Methodology deep dive
- skills/ralph-plan-generator.md - Plan generator documentation
MIT