Claude Meets Ralph

Autonomous task executor for Claude Code CLI. Ralph lets you plan tasks, queue them, and have Claude execute them autonomously with a hook-based iteration loop.

Installation

npm install -g claude-meets-ralph

Quick Start

# Initialize Ralph in your project
cd your-project
ralph init

# Plan a new task (Claude will ask clarifying questions)
ralph new "Add user authentication with JWT"

# Review and approve the task
ralph approve 2026-01-12-add-user-authentication.md

# Execute the task autonomously
ralph run

# Check status
ralph status

Requirements

• Node.js 18+
• Bash 4+
• Claude CLI installed and authenticated
• jq (for JSON processing in hooks)

Commands

ralph init

Initialize Ralph in your project. Creates:

• .ralph/ directory structure (planning, pending, complete, failed, analytics, logs)
• .claude/hooks/ralph-stop-hook.sh - Hook that manages the iteration loop
• .claude/commands/ralph-cancel.md - Command to cancel an active loop
• .claude/settings.local.json - Hook configuration (merged with existing)

ralph new "description"

Start an interactive planning session with Claude. Claude will:

1. Ask clarifying questions until 10/10 confidence
2. Create a structured task document with:
   • Goal
   • Completion Criteria (checklist items)
   • Sub-tasks (TDD-focused)
   • Self-Correction instructions
   • Context and Technical Notes

ralph edit <file> "changes"

Edit an existing task file with Claude's help. Preserves required sections and validates structure.

ralph approve <file>

Move a task from planning to pending queue. Validates the task has required sections and checklist items.

ralph run [--max-iter N]

Execute pending tasks autonomously. Default max iterations: 20.

The hook-based loop:

1. Claude works on unchecked items
2. When Claude tries to exit, the stop hook checks if all criteria are met
3. If incomplete, the hook continues the session with a new prompt
4. Loop ends when all items checked or max iterations reached

ralph status

Show all tasks organized by status (planning, pending, complete, failed).

How It Works

Ralph uses Claude's hook system to create an autonomous execution loop:

1. Planning Phase: You describe a task, Claude asks questions until it fully understands
2. Approval: You review the task document and move it to the pending queue
3. Execution: Claude executes sub-tasks, checking items off as it goes
4. Loop Control: The stop hook intercepts session exits and continues if work remains
5. Completion: Task moves to complete/ or failed/ based on outcome

Task Document Format

# Task: [Title]

## Goal
[Clear description]

## Completion Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Sub-tasks
- [ ] Write tests for feature
- [ ] Implement feature to pass tests

## Self-Correction
[How to detect and recover from mistakes]

## Context
[Additional notes]

## Technical Notes
[Implementation details]

Emergency Escape Hatch

If Claude gets completely stuck, it can add this marker to stop the loop:

<!-- RALPH:BLOCKED: reason why progress is impossible -->

Use only when human intervention is required (missing credentials, impossible requirements, etc.).

Project Structure

After ralph init, your project will have:

your-project/
├── .ralph/
│   ├── planning/    # Tasks being planned
│   ├── pending/     # Tasks queued for execution
│   ├── complete/    # Successfully completed tasks
│   ├── failed/      # Tasks that hit max iterations
│   ├── analytics/   # Execution metrics (JSON)
│   └── logs/        # Execution logs
├── .claude/
│   ├── hooks/
│   │   └── ralph-stop-hook.sh
│   ├── commands/
│   │   └── ralph-cancel.md
│   └── settings.local.json
└── .gitignore       # Updated with ralph entries

Tips

• TDD Focus: Task documents emphasize writing tests before implementation
• Atomic Commits: Claude commits after each code-editing sub-task
• Conventional Commits: Uses format like feat(auth): add JWT validation
• Review Tasks: Always review the task document before approving
• Start Small: Begin with smaller tasks to understand the workflow

License

MIT