ralph

Custom CLI for running Ralph loops using claude in docker sandboxes with git worktree isolation.

Install

chmod +x install.sh ralph
./install.sh

Installs (symlinks) to:

• /usr/local/bin/ralph
• /usr/local/share/zsh/site-functions/_ralph (completions)

Usage

ralph new <feature>      # Create worktree + branch, start PRD session
ralph run <feature>      # Run automated loop (default 10 iterations)
ralph run 5 <feature>    # Run with custom iteration count
ralph run-once <feature> # Single iteration
ralph chat <feature>     # Interactive session

How it works

• ralph new creates a git worktree at ../<project>-ralph-worktrees/<feature> with branch ralph/<feature>
• Copies files listed in .worktreeinclude to the new worktree
• Runs Claude in a docker sandbox with the worktree mounted
• PRD and progress tracked in .ralph/ within each worktree

Troubleshooting

Git not working in sandbox

If Claude can't access git in the sandbox:

fatal: not a git repository: /path/to/main-repo/.git/worktrees/<feature>

The sandbox was likely created before the volume mount fix. Remove it and retry:

docker sandbox ls                  # Find the sandbox ID
docker sandbox rm <sandbox-id>     # Remove it
ralph run <feature>                # Will create new sandbox with correct mounts

Requirements

• Docker with docker sandbox support
• Git
• Claude CLI