---

🤔 Why Ralph CLI over the official Claude Code plugin?

| Feature | Ralph CLI | Claude Code Built-in |
|---------|-----------|---------------------|
| Context Management | ✅ Fresh context each iteration | ❌ Context accumulates and degrades |
| Memory Persistence | ✅ Git + progress.txt + prd.json | ❌ Lost between sessions |
| Multi-repo Support | ✅ Native support for monorepos | ❌ Single repo at a time |
| Quality Gates | ✅ Automated checks between stories | ❌ Manual verification |
| Progress Tracking | ✅ Structured PRD with status | ❌ No built-in tracking |
| Branch Management | ✅ Auto-create, fork, checkout | ❌ Manual git operations |
| Iteration Control | ✅ Configurable max iterations | ❌ No automatic limits |

The key insight: Claude Code's context window fills up over long sessions, degrading output quality. Ralph solves this by spawning fresh instances for each story, using files as persistent memory instead of relying on in-context state.

> 💡 "The 'Ralph' pattern is about context hygiene. Each iteration starts clean, with only the essential context loaded from files."

---

📑 Table of Contents

- 🤔 Why Ralph CLI?
- 🚀 How It Works
- 📦 Installation
- ⚡ Quick Start
- 💻 CLI Commands
- 📋 Prerequisites
- ⚙️ Configuration Reference
- 📝 Story Guidelines
- 🔀 Branch Forking
- 📁 Archiving
- 🛠️ Development
- 📚 References
- 📄 License

---

🚀 How It Works

``
┌─────────────────────────────────────────────────────────────┐
│ 🔄 Ralph Workflow │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. ralph init 🎯 Initialize configuration │
│ ↓ │
│ 2. ralph plan 📝 Generate a structured plan │
│ ↓ │
│ 3. ralph prd 🔧 Convert plan to prd.json │
│ ↓ │
│ 4. ralph run 🤖 Execute stories autonomously │
│ ↓ │
│ 5. Commits + PRD ✅ Each story committed │
│ │
└─────────────────────────────────────────────────────────────┘
`

---

📦 Installation

`bash
npm install -g claude-ralph
`

Or use npx without installing:

`bash
npx claude-ralph
`

---

⚡ Quick Start

$3

`bash
cd your-project
ralph init
`

This creates ralph.config.json with your project settings.

$3

Edit ralph.config.json:

`json
{
"project": "MyProject",
"description": "My awesome project",
"repositories": {
"backend": {
"path": "./backend",
"checks": ["pytest", "mypy ."]
},
"frontend": {
"path": "./frontend",
"checks": ["npm run build", "npm run lint"]
}
}
}
`

Single repository? Just use one entry:

`json
{
"project": "MyProject",
"repositories": {
"main": {
"path": ".",
"checks": ["npm run build", "npm test"]
}
}
}
`

$3

`bash
ralph plan "Add user authentication with OAuth support"
`

Claude will:
1. 🤔 Ask 3-5 clarifying questions
2. 📄 Generate plan.md with structured user stories
3. ✅ Ask for validation

$3

Review and edit plan.md if needed, then:

`bash
ralph prd
`

This converts the plan to prd.json.

$3

`bash
ralph run
`

Ralph will:
1. 🎯 Pick the highest priority story with passes: false
2. 📂 Navigate to the correct repository
3. 🌿 Create/checkout the feature branch
4. 💻 Implement the story
5. 🧪 Run quality checks
6. ✅ Commit if checks pass
7. 🔄 Update prd.json and repeat

$3

`bash
ralph status
ralph status --verbose
`

---

💻 CLI Commands

| Command | Description |
|---------|-------------|
| ralph init | 🎯 Initialize Ralph configuration |
| ralph plan | 📝 Generate a structured implementation plan |
| ralph prd | 🔧 Convert plan.md to prd.json |
| ralph run | 🤖 Run the autonomous agent loop |
| ralph status | 📊 Show current progress and status |

$3

Initialize Ralph configuration in the current directory.

`bash
ralph init
ralph init --force # Overwrite existing config
`

$3

Generate a structured implementation plan.

`bash
ralph plan "Add a notification system with email and push support"
ralph plan "Refactor the auth module" --output custom-plan.md
`

$3

Convert plan.md to prd.json.

`bash
ralph prd
ralph prd --input custom-plan.md --output custom-prd.json
`

$3

Run the autonomous agent loop.

`bash
ralph run
ralph run --max-iterations 10 # Limit iterations
`

$3

Show current progress and status.

`bash
ralph status
ralph status --verbose # Show detailed information
`

---

📋 Prerequisites

- 🧠 Claude Code CLI installed and authenticated
- 📦 Node.js 18 or later

---

⚙️ Configuration Reference

$3

`json
{
"$schema": "https://raw.githubusercontent.com/anthropics/ralph/main/schema/ralph.config.schema.json",
"version": "1.0",
"project": "MyProject",
"description": "Optional project description",
"repositories": {
"repo-key": {
"path": "./relative/path",
"defaultBranch": "main",
"checks": [
"command1",
"command2"
]
}
},
"agent": {
"maxIterations": 50,
"timeout": 600
}
}
`

Configuration can also be stored in:
- .ralphrc
- .ralphrc.json
- .ralphrc.yaml
- package.json under the "ralph" key

$3

`json
{
"project": "Feature Name",
"description": "What this feature does",
"repositories": {
"backend": { "branchName": "feature/my-feature" },
"frontend": { "branchName": "feature/my-feature" }
},
"userStories": [
{
"id": "US-001",
"title": "Add user model",
"repo": "backend",
"description": "As a developer, I need a user model...",
"acceptanceCriteria": [
"User model created with email, password fields",
"Migration generated",
"Tests pass"
],
"priority": 1,
"passes": false,
"fork": false,
"notes": ""
}
]
}
`

---

📝 Story Guidelines

$3

For significant direction changes, use fork: true in a story:

`json
{
"id": "US-005",
"title": "Refactor auth system",
"fork": true,
"passes": false
}
`

Ralph will create a new branch (e.g., feature/auth-2) from the current one.

---

📁 Archiving

Ralph automatically archives previous runs when you start a new project. Archives are saved in archive/YYYY-MM-DD-project-name/.

---

🛠️ Development

To build from source:

`bash
git clone https://github.com/anthropics/ralph.git
cd ralph
npm install
npm run build
npm link # Makes 'ralph' command available globally
``

---

📚 References

- 🎩 Geoffrey Huntley's Ralph article
- 🧠 Claude Code documentation

---

📄 License

MIT License - see LICENSE

---