Skip to content

AGENTS.md

Latest commit

 

History

History
97 lines (70 loc) · 2.87 KB

AGENTS.md

File metadata and controls

97 lines (70 loc) · 2.87 KB
Raw

Ralph - Autonomous AI Agent Loop

Ralph is an autonomous AI agent loop runner that runs Claude Code or Codex repeatedly until all PRD items are complete.

Prerequisites

  • Claude Code CLI: Install with npm install -g @anthropic-ai/claude-code
  • Codex CLI: Install with npm install -g @openai/codex
  • jq: Install with brew install jq (macOS) or apt install jq (Ubuntu/Debian)

Installation

Make the ralph script executable:

chmod +x ralph

Optionally, add it to your PATH or create a symlink.

Commands

Initialize a Project

./ralph init              # Initialize in current directory
./ralph init ./my-project # Initialize in specific directory
./ralph init --profile mobile-smart # Initialize Mobile Smart .ralph profile

The default profile creates:

  • prd.json - PRD with user stories (edit this with your tasks)
  • CLAUDE.md - Instructions for Claude Code instances
  • CODEX.md - Instructions for Codex instances
  • AGENTS.md - Documentation for Ralph agents
  • prompt.md - Instructions for AMP instances
  • progress.txt - Progress log

The mobile-smart profile creates only .ralph/* files and does not overwrite root project agent files.

Run the Agent Loop

./ralph run               # Run with default 10 iterations
./ralph run --tool codex  # Run with Codex
./ralph run --max 20      # Run up to 20 iterations
./ralph run -m 5          # Short form for max iterations
./ralph run --config .ralph/config.json # Run with explicit config
./ralph run --dry-run     # Show config without running

Other Commands

./ralph help              # Show help
./ralph version           # Show version

How It Works

  1. Ralph reads your configured PRD to find user stories
  2. Each iteration spawns a fresh Claude Code or Codex instance
  3. The agent picks the highest priority incomplete story and implements it
  4. When a story is complete, the agent updates the PRD to mark it as passes: true
  5. The loop continues until all stories pass or max iterations is reached
  6. If the PRD shows every story passing, Ralph exits successfully

Key Files

File Purpose
ralph The main CLI script
prd.json PRD with user stories and acceptance criteria
CLAUDE.md Instructions given to each Claude Code instance
CODEX.md Instructions given to each Codex instance
progress.txt Log of completed work and learnings
archive/ Archived runs from previous branches

Example Workflow

# 1. Initialize ralph in your project
cd my-project
/path/to/ralph init

# 2. Edit prd.json with your user stories
vim prd.json

# 3. Run the agent loop
/path/to/ralph run

# 4. Watch as Ralph completes your stories

Stopping Ralph

Press Ctrl+C to stop the loop at any time. Progress is saved in progress.txt and completed stories remain marked as passes: true in prd.json.