Ralph

# Getting Started with Ralph ## What is Ralph? Ralph is a **harness** for AI coding CLIs. It runs tools like Claude Code or Gemini CLI in a loop until specific completion criteria are met. Think of it as a project manager for your AI coding assistants. ## Prerequisites - An AI coding CLI installed (Claude Code, Gemini CLI, or OpenCode) - Bash 4.0+ - Git - tmux (recommended for monitoring) - jq (for status tracking) ## Installation ### Via Script ```bash git clone https://github.com/ralph-ai/ralph cd ralph ./install.sh ``` This adds `ralph`, `ralph-monitor`, and `ralph-setup` to your PATH. ### Via Bun (Ralph TUI) ```bash bun install -g ralph-tui ``` ## Quick Start ### 1. Initialize Your Project ```bash cd your-project ralph-tui setup ``` This creates `.ralph-tui/config.toml` and detects installed AI agents. ### 2. Create a PRD (Product Requirements Document) ```bash ralph-tui create-prd --chat ``` The AI will ask about: - Feature goals - Requirements - Quality gates (tests must pass, linting clean, etc.) ### 3. Run Ralph ```bash ralph prompt.md --completion-signal "DONE" --max-iterations 10 ``` Ralph will: 1. Read your instructions 2. Execute the AI coding agent 3. Track progress in `progress.txt` 4. Loop until completion or max iterations ## Key Concepts ### Completion Criteria Define clear, verifiable criteria: - ✅ "All unit tests pass" - ✅ "ESLint reports 0 warnings" - ❌ "Good code quality" (too vague) ### Progress Tracking Ralph uses: - `progress.txt`: Current status and decisions - `AGENTS.md`: Learnings between iterations ### HITL to AFK Workflow 1. **Human-In-The-Loop**: Monitor first few runs 2. **Away-From-Keyboard**: Let Ralph work autonomously ## Best Practices - Start with HITL, then go AFK - Define clear completion criteria - Take small steps (better code quality) - Use Docker sandboxes for safety - Set reasonable max-iterations to control costs