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

``bash
npm install -g claude-meets-ralph
`

Quick Start

`bash


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

$3

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)

$3

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

$3

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

$3

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

$3

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

$3

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

$3

`markdown


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]
`

$3

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

`

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