Installation

Installation

ralph is distributed as an npm package and works on macOS, Linux, and Windows (via WSL).

Prerequisites

Before installing ralph, ensure you have:

• Node.js 18+ — ralph uses modern JavaScript features
• An AI CLI tool — Claude Code or OpenCode currently supported.
• VCS — For state persistence between iterations use git, jj or your preferred version control system.

Note

ralph orchestrates other AI tools—it doesn’t include an AI model itself. You’ll need at least one AI CLI tool installed.

Install ralph

npm

npm install -g @wiggumdev/ralph

pnpm

pnpm add -g @wiggumdev/ralph

yarn

yarn global add @wiggumdev/ralph

bun

bun add -g @wiggumdev/ralph

Verify the installation:

ralph --version

Install an AI Tool

ralph needs an AI CLI tool to orchestrate. Here are the supported options:

Configuration

1. Initialize ralph in your project

   Navigate to your project directory and run:

   cd your-project
   ralph init

   This creates .ralph/config.toml and the .plans/ directory.

2. Configure your adapter

   Edit .ralph/config.toml:

   adapter = "claude"
   maxIterations = 10

3. Use your agent to plan

   • Use the ralph-prd skill

   or

   • Use your ai tool create a plan for the functionlality you want to implememt.
   • Review the plan and make any required changes.
   • Ask your AI to break down the plan into the ralph prd.json file

4. Create your task prompt

   Edit .plans/PROMPT.md with your task:

   @.plans/prd.json @.plans/progress.txt
   run `git log --limit 10`
   
   1. Select the highest-priority feature to work on and work ONLY on that feature. This should be the one YOU decide has the highest priority - not necessarily the first in the list. `cat .plans/prd.json | jq '[.[] | select(.passes == false)]'`
   2. Before making changes, search codebase (don't assume not implemented).
   3. Implement the requirements for the selected feature using TDD.
   3. Run typecheck and tests: `bun run typecheck && bun run test`
   4. Update prd.json marking completed work (CAREFULLY!)
       **YOU CAN ONLY MODIFY ONE FIELD: "passes"**
       After thorough verification, change:
       ```json
       "passes": false
       ```
       to:
       ```json
       "passes": true
       ```
   5. Reflect on what you have done and APPEND learning to .plans/progress.txt for future iterations.
   6. Commit changes: `git add . && git commit -m "<description/>"`
   7. If all features complete, output `<promise>COMPLETE</promise>`
   
   
   IMPORTANT RULES:
   - ONLY WORK ON A SINGLE FEATURE PER ITERATION.
   - When you learn something new about how to run commands or patterns in the code make sure you update @CLAUDE.md using a subagent but keep it brief.
   - If you find a bug or issue, add it to the .plans/next.md
   
   REMEMBER: You have unlimited time across many sessions. Focus on quality over speed. Production-ready is the goal.

Troubleshooting

”Command not found: ralph”

Ensure npm’s global bin directory is in your PATH:

export PATH="$PATH:$(npm config get prefix)/bin"

“AI tool not found”

Make sure your AI tool is installed and accessible:

which claude  # or: which opencode

Permission errors

On macOS/Linux, you may need to fix npm permissions:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH="$PATH:$HOME/.npm-global/bin"

Next Steps

With ralph installed, you’re ready to run your first loop:

→ Quick Start Guide