Quick Start

Ralph has two phases: one-time installation and per-project setup.

INSTALL ONCE              USE MANY TIMES
+-----------------+          +----------------------+
| ./install.sh    |    ->    | ralph-setup project1 |
|                 |          | ralph-enable         |
| Adds global     |          | ralph-import prd.md  |
| commands        |          | ...                  |
+-----------------+          +----------------------+

Phase 1: Install Ralph (One Time Only)

Install Ralph globally on your system:

git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code
./install.sh

This adds ralph, ralph-monitor, ralph-setup, ralph-import, ralph-queue, ralph-migrate, ralph-enable, and ralph-enable-ci commands to your PATH.

Note: You only need to do this once per system. After installation, you can delete the cloned repository if desired.

- .ralph/specs/requirements.md (technical specs)

Configure your project requirements manually

Importing Existing Requirements

Ralph can convert existing PRDs, specifications, or requirement documents into the proper Ralph format using Claude Code.

Also import issue comments (e.g. when a plan was posted as a comment)

ralph-import --github-issue 42 --include-comments

The issue title becomes the project name (slugified, e.g. `Add User Login` → `add-user-login`) and the issue body becomes the PRD content. `--github-issue` addresses an exact issue and cannot be combined with the filter flags below.

---

### Completeness Assessment and Plan Generation

GitHub issues vary widely in detail. During import, Ralph scores the issue 0–100 for implementation readiness (acceptance criteria, task checklists, code examples, section structure, guidance keywords, length). Issues scoring below the threshold (default: 60) get an implementation plan generated by Claude Code before conversion — the plan is folded into the generated `fix_plan.md` tasks and preserved verbatim at `.ralph/specs/implementation-plan.md`.

```bash

---

# Default: assess the issue, generate a plan only if it lacks detail
ralph-import --github-issue 42

---

# Always generate a plan, with a specific model
ralph-import --github-issue 42 --generate-plan --plan-model opus

---

# Never generate a plan (fails if the issue scores below the threshold)
ralph-import --github-issue 42 --no-generate-plan

---

## Docker Sandbox Execution

Run Claude Code inside an isolated Docker container instead of directly on your machine (Issue #74). Ralph's loop, rate limiting, and monitoring stay on the host; only Claude's execution — the part that edits files and runs commands autonomously — is containerized. The project directory is bind-mounted read-write at `/workspace`, so changes land on the host directly and `ralph-monitor` works unchanged.

---

# ...or build it yourself (from a source checkout, or ~/.ralph after install)
docker build -t ralph-sandbox .

System Requirements

• Bash 4.0+ - For script execution
• Claude Code CLI - npm install -g @anthropic-ai/claude-code (or use npx — set CLAUDE_CODE_CMD in .ralphrc)
• tmux - Terminal multiplexer for integrated monitoring (recommended)
• jq - JSON processing for status tracking
• Git - Version control (projects are initialized as git repos)
• GNU coreutils - For the timeout command (execution timeouts)
  • Linux: Pre-installed on most distributions
  • macOS: Install via brew install coreutils (provides gtimeout)
• Standard Unix tools - grep, date, etc.

Testing Requirements (Development)

See TESTING.md for the comprehensive testing guide.

If you want to run the test suite:

---

# Install BATS testing framework
npm install -g bats bats-support bats-assert

---

# Install coreutils (provides gtimeout)
brew install coreutils

---

# Verify installation
gtimeout --version

Ralph autom