Frequently Asked Questions

General Questions

What is Ralph?

Ralph is a CLI tool that orchestrates AI coding agents to work through Product Requirements Documents (PRDs) autonomously. It manages long-running development sessions with automatic retries, progress tracking, and GitHub integration.

Think of Ralph as a supervisor for your AI coding agent. Instead of manually prompting the agent repeatedly, Ralph automates the entire workflow: feeding tasks, monitoring progress, handling failures, and tracking what’s been completed.

Which AI agents does Ralph support?

Ralph supports three AI coding agents:

  • Cursor CLI — The most commonly used option, requires Cursor Pro subscription
  • Claude Code — Anthropic’s Claude Code CLI
  • Codex — OpenAI’s Codex CLI

You can switch between agents per-project or globally via configuration.

Is Ralph free?

Yes, Ralph itself is free and open source under the MIT license. You can:

  • Use it for personal or commercial projects
  • Modify the source code
  • Contribute improvements

However, you need a subscription to the AI agent you choose:

  • Cursor Pro for Cursor CLI
  • Claude API access for Claude Code
  • OpenAI API access for Codex

Does Ralph work offline?

No, Ralph requires internet access because:

  • AI agents connect to their respective APIs (Anthropic, OpenAI, etc.)
  • GitHub integration requires network access
  • Package managers need to download dependencies

However, Ralph itself doesn’t require internet beyond what the AI agent needs.

What programming languages does Ralph support?

Ralph is language-agnostic. It works with any programming language or framework because it orchestrates the AI agent, which handles the actual coding.

Successfully used with:

  • JavaScript/TypeScript (Node.js, React, Next.js)
  • Python (Django, Flask, FastAPI)
  • Go
  • Rust
  • Ruby (Rails)
  • PHP (Laravel)
  • Java/Kotlin
  • And more

How is Ralph different from using an AI agent directly?

Using Agent DirectlyUsing Ralph
Manual prompting for each taskAutomatic task orchestration
No progress trackingPersistent progress across sessions
Manual retry on failuresAutomatic retries with context
Lose context between sessionsSession memory and learning
Manual GitHub operationsAutomated PR creation
No structured workflowPRD-driven systematic approach

Ralph adds structure, automation, and reliability to AI-assisted development.

Installation & Setup

How do I install Ralph?

The easiest way is the automated install script:

curl -fsSL https://raw.githubusercontent.com/nitodeco/ralph/main/scripts/install.sh | bash

This automatically:

  • Detects your OS and architecture
  • Downloads the appropriate binary
  • Installs to ~/.local/bin
  • Adds to your PATH if needed

See Installation Guide for manual installation and troubleshooting.

What are the system requirements?

Required:

  • macOS, Linux, or Windows (via WSL)
  • One of the supported AI agents (Cursor CLI, Claude Code, or Codex)
  • Git for version control

Optional:

  • GitHub account (for PR creation and integration)
  • Bun or Node.js 18+ (only if building from source)

How do I update Ralph?

ralph update

This checks for the latest version and installs it automatically.

Or manually re-run the install script:

curl -fsSL https://raw.githubusercontent.com/nitodeco/ralph/main/scripts/install.sh | bash

Can I install Ralph without the install script?

Yes, download the binary directly from the releases page:

# macOS (Apple Silicon)
curl -L https://github.com/nitodeco/ralph/releases/latest/download/ralph-macos-arm64 -o ralph

# macOS (Intel)
curl -L https://github.com/nitodeco/ralph/releases/latest/download/ralph-macos-x64 -o ralph

# Linux
curl -L https://github.com/nitodeco/ralph/releases/latest/download/ralph-linux-x64 -o ralph

chmod +x ralph
mv ralph ~/.local/bin/

Where does Ralph store data?

Ralph stores all data in ~/.ralph/:

~/.ralph/
├── config.json              # Global configuration
├── registry.json            # Project registry
├── usage-statistics.json    # Usage stats
└── projects/                # Per-project data
    └── <project-name>/
        ├── config.json      # Project config
        ├── prd.json         # PRD file
        ├── session.json     # Session state
        ├── guardrails.json  # Guardrails
        ├── instructions.md  # Custom instructions
        └── logs/            # Iteration logs

How do I uninstall Ralph?

Remove the binary:

rm ~/.local/bin/ralph

Optionally remove all data:

rm -rf ~/.ralph

Usage & Workflow

How do I start a new project?

Navigate to your project directory and run:

ralph init

Ralph will:

  1. Ask you to describe what you want to build
  2. Generate a PRD with 5-15 tasks
  3. Let you choose your AI agent (Cursor, Claude, or Codex)
  4. Save everything to ~/.ralph/projects/<project>/

How do I run Ralph?

Start a session with:

ralph run

This runs 10 iterations by default. For more iterations:

ralph run 20    # Run 20 iterations
ralph run 50    # Run 50 iterations

For long-running sessions, use background mode:

ralph run -b    # Run in background

How do I stop Ralph?

If running in foreground:

# Press Ctrl+C
^C

If running in background:

ralph stop

Ralph stops gracefully after completing the current iteration.

How do I check progress?

Multiple commands show different aspects of progress:

ralph status        # Overall session status
ralph progress      # Progress notes
ralph task list     # Task completion
ralph task current  # Next task to work on

Example output:

$ ralph status
Session Status:
  State: Running
  Iteration: 5 / 10
  Started: 15 minutes ago
  
Current Task:
  [4] Implement user signup endpoint
  
Recent Progress:
  ✓ Set up Express server (3 minutes)
  ✓ Configure PostgreSQL (4 minutes)
  ✓ Create user schema (5 minutes)

Can I run Ralph in the background?

Yes, use the -b or --background flag:

ralph run -b

Ralph detaches from the terminal and continues running. Monitor with:

ralph status        # Check status
ralph progress      # View progress
ralph task list     # See completed tasks

View logs:

tail -f ~/.ralph/projects/<project>/logs/latest.log

Can I pause and resume a session?

Yes, Ralph maintains session state:

Pause:

ralph stop
# or press Ctrl+C

Resume:

ralph resume

Ralph picks up exactly where it left off, including:

  • Current task
  • Iteration count
  • Progress notes
  • Error history

How long does a session take?

It depends on:

  • Number of tasks in your PRD
  • Complexity of each task
  • Configured timeouts
  • Number of iterations

Typical sessions:

  • Simple CRUD API (8 tasks): 1-2 hours
  • Full-stack feature (15 tasks): 3-5 hours
  • Complex refactor (20+ tasks): 6-12 hours

You can run overnight sessions with:

ralph run 100 -b

What if I need to make manual changes during a session?

You can:

  1. Stop the session:

    ralph stop

  2. Make your changes manually

  3. Mark tasks as done if needed:

    ralph task done 5
ralph progress add "Completed manually"

  4. Resume:

    ralph resume

Ralph continues with the next pending task.

Can I run multiple projects simultaneously?

Yes, Ralph supports multiple projects:

cd project-a
ralph run -b

cd ../project-b
ralph run -b

Each project maintains independent:

  • PRD and tasks
  • Session state
  • Configuration
  • Progress tracking

View all projects:

ralph projects

Tasks & PRDs

What is a PRD?

A Product Requirements Document (PRD) is a structured list of tasks that defines what you want to build. Ralph uses the PRD to guide the AI agent through your project systematically.

Example PRD:

1. Set up Express server with TypeScript
2. Configure PostgreSQL database
3. Create user authentication schema
4. Implement signup endpoint
5. Implement login endpoint
6. Add JWT token generation
7. Create authentication middleware
8. Protect API routes

Can I edit the PRD manually?

Yes, but use Ralph commands when possible:

ralph task add --title "New task"
ralph task edit 5 --title "Updated title"
ralph task remove 3
ralph task done 4
ralph task undone 5

The PRD file is stored at ~/.ralph/projects/<project>/prd.json if you need to edit it directly.

How do I add more tasks?

Several ways:

During initialization:

ralph init  # Generates tasks based on your description

Add individual tasks:

ralph task add --title "Add rate limiting"

Add with details:

ralph task add \
  --title "Add rate limiting" \
  --description "Protect API from abuse" \
  --steps "Install express-rate-limit" \
  --steps "Configure limits"

What makes a good task?

Good tasks are:

Specific:

Bad:  Add authentication
Good: Implement JWT-based authentication with signup and login endpoints

Appropriately scoped:

Too large: Build entire authentication system
Too small: Import bcrypt library
Just right: Implement user signup endpoint with validation and password hashing

Self-contained:

Bad:  Create API endpoint (will add validation later)
Good: Create API endpoint with input validation and error handling

Action-oriented:

Create user database schema
Implement password reset flow
Add rate limiting to API endpoints
Refactor database queries to use transactions

See Core Concepts: PRDs for detailed guidelines.

Can Ralph break down large tasks automatically?

Yes, Ralph supports automatic task decomposition. If the AI agent detects a task is too complex, it can:

  1. Output a DECOMPOSE_TASK marker
  2. Provide a list of subtasks
  3. Ralph replaces the original task with subtasks
  4. Continues with the first subtask

Example:

Original:
[ ] 5. Build authentication system

Decomposed:
[ ] 5.1. Create user schema
[ ] 5.2. Implement signup endpoint
[ ] 5.3. Implement login endpoint
[ ] 5.4. Add JWT generation
[ ] 5.5. Create auth middleware

How do I reorder tasks?

Tasks are processed in order. To reorder:

  1. Mark completed tasks as undone:

    ralph task undone 5
ralph task undone 6

  2. Complete tasks in desired order:

    ralph task done 6
ralph task done 5

Or edit the PRD file directly to reorder tasks.

What if a task is no longer needed?

Remove it:

ralph task remove 5
ralph progress add "Removed task 5 - no longer needed"

Or mark it done to skip it:

ralph task done 5
ralph progress add "Skipped - requirement changed"

Configuration & Customization

Where is configuration stored?

Ralph uses a layered configuration system:

  • Global: ~/.ralph/config.json (defaults for all projects)
  • Per-project: ~/.ralph/projects/<project>/config.json (overrides global)

Project settings override global settings.

How do I change the AI agent?

Interactive setup:

ralph setup

Edit global config:

echo '{"agent": "claude"}' > ~/.ralph/config.json

Edit project config:

echo '{"agent": "claude"}' > ~/.ralph/projects/<project>/config.json

Supported agents: cursor, claude, codex

How do I increase timeouts?

Edit your config file:

{
  "agentTimeoutMs": 3600000,
  "stuckThresholdMs": 600000
}

Common timeout values:

  • 1800000 (30 min) — Default
  • 3600000 (1 hour) — Complex tasks
  • 5400000 (90 min) — Large refactors
  • 7200000 (2 hours) — Migrations

See Configuration Guide for all options.

Can I customize agent instructions?

Yes, create ~/.ralph/projects/<project>/instructions.md:

# Project Instructions

## Technology Stack
- TypeScript with strict mode
- Bun as runtime
- Prisma for database

## Code Standards
- Use functional programming
- Write descriptive variable names
- Add JSDoc for public APIs

## Project Structure
- API routes in src/routes/
- Business logic in src/services/
- Database models in src/models/

Ralph includes these instructions in every agent prompt.

How do I configure notifications?

Edit your config:

{
  "notifications": {
    "systemNotification": true,
    "webhookUrl": "https://hooks.slack.com/services/...",
    "markerFilePath": ".ralph/complete.marker"
  }
}

Options:

  • systemNotification: OS notification on completion
  • webhookUrl: POST to webhook (Slack, Discord, etc.)
  • markerFilePath: Create file when done

Can I have different settings per project?

Yes, project config overrides global config:

Global (default for all projects):

cat > ~/.ralph/config.json << EOF
{
  "agent": "cursor",
  "agentTimeoutMs": 1800000
}
EOF

Project-specific:

cat > ~/.ralph/projects/my-project/config.json << EOF
{
  "agent": "claude",
  "agentTimeoutMs": 3600000
}
EOF

This project uses Claude with 1-hour timeout, while others use global settings.

GitHub Integration

Do I need GitHub to use Ralph?

No, GitHub integration is completely optional. Ralph works perfectly for local development without any GitHub connection.

Use GitHub integration if you want:

  • Automatic PR creation
  • Branch management
  • Commit pushing to remote

How do I connect GitHub?

Authenticate with OAuth device flow:

ralph auth login

Follow the prompts:

  1. Ralph displays a code and URL
  2. Open the URL in your browser
  3. Enter the code
  4. Authorize the Ralph application
  5. Return to terminal

Verify authentication:

ralph auth

See GitHub Integration Guide for details.

Can Ralph create pull requests automatically?

Yes, after authenticating:

ralph auth login

Ralph can create PRs from completed work. Configure PR creation in your workflow or use commands:

# After completing tasks
ralph github create-pr --title "Feature: User Authentication" --body "Implemented signup and login"

What GitHub permissions does Ralph need?

Ralph requests:

  • repo — Read/write access to repositories (create branches, push commits, create PRs)
  • read:user — Read your user profile

These are the minimum permissions needed for full functionality.

Can I use a personal access token instead of OAuth?

Yes, if you prefer:

  1. Create a token at GitHub Settings > Tokens
  2. Grant repo scope
  3. Set the token:
ralph github set-token ghp_xxxxxxxxxxxxx

OAuth is recommended for better security and automatic token refresh.

How do I disconnect GitHub?

ralph auth logout

This clears stored credentials. You can reconnect anytime with ralph auth login.

Troubleshooting & Common Issues

Ralph keeps retrying the same task

Causes:

  • Task is too complex
  • Task description is unclear
  • Agent lacks necessary context
  • Technical blocker (missing dependency, etc.)

Solutions:

  1. Break the task down:

    ralph task remove 5
ralph task add --title "Subtask 1: Setup"
ralph task add --title "Subtask 2: Implementation"

  2. Add more context via guardrails:

    ralph guardrails add "For authentication, use the pattern from src/auth/example.ts"

  3. Check logs for specific errors:

    tail -f ~/.ralph/projects/<project>/logs/latest.log

  4. Complete manually:

    # Do the work yourself
ralph task done 5
ralph progress add "Completed manually - agent struggled with X"

Agent times out frequently

Causes:

  • Tasks are too complex
  • Default timeout (30 min) is too short
  • System is slow or under load

Solutions:

  1. Increase timeout:

    {
  "agentTimeoutMs": 3600000
}

  2. Break tasks into smaller pieces:

    ralph task edit 5 --title "Smaller, more focused task"

  3. Check system resources:

    top
free -h

Agent appears stuck (no output)

Causes:

  • Agent is processing large files
  • Network issues
  • Agent crashed but process didn’t exit

Solutions:

  1. Reduce stuck threshold:

    {
  "stuckThresholdMs": 180000
}

  2. Check agent process:

    ps aux | grep cursor

  3. Kill if hung:

    kill -9 <pid>
ralph run  # Ralph will retry

Where are the logs?

Logs are stored in:

~/.ralph/projects/<project>/logs/
├── latest.log           # Current session
├── 2024-01-20.log      # Daily logs
└── ...

View logs:

# Latest log
tail -f ~/.ralph/projects/<project>/logs/latest.log

# Search for errors
grep -i error ~/.ralph/projects/<project>/logs/*.log

# View specific date
cat ~/.ralph/projects/<project>/logs/2024-01-20.log

See Troubleshooting Guide for more solutions.

How do I debug issues?

  1. Check logs:

    tail -f ~/.ralph/projects/<project>/logs/latest.log

  2. Check session status:

    ralph status

  3. Review failure patterns:

    ralph analyze patterns

  4. Check configuration:

    ralph config

  5. Verify agent is accessible:

    which cursor  # or claude, codex

What if I encounter a bug?

  1. Check existing issues: Ralph GitHub Issues

  2. Open a new issue with:

    • Ralph version: ralph --version
    • Agent being used: From ralph config
    • Operating system: uname -a
    • Error message: Full error text
    • Steps to reproduce
    • Relevant log excerpts

  3. Include logs:

    cat ~/.ralph/projects/<project>/logs/latest.log

Advanced Usage

Can I use Ralph with CI/CD?

Yes, Ralph can run in CI/CD pipelines:

# GitHub Actions example
- name: Run Ralph
  run: |
    ralph run 20 --json > results.json
    
- name: Check completion
  run: |
    DONE=$(cat results.json | jq '.done')
    TOTAL=$(cat results.json | jq '.total')
    if [ "$DONE" -ne "$TOTAL" ]; then
      exit 1
    fi

Configure for CI/CD:

{
  "agentTimeoutMs": 600000,
  "maxRetries": 2,
  "notifications": {
    "systemNotification": false,
    "markerFilePath": "/tmp/ralph-complete"
  }
}

Can I run Ralph on a remote server?

Yes, Ralph works on any Linux server:

# SSH into server
ssh user@server

# Install Ralph
curl -fsSL https://raw.githubusercontent.com/nitodeco/ralph/main/scripts/install.sh | bash

# Run in background
ralph run -b

# Disconnect (Ralph keeps running)
exit

# Later, check progress
ssh user@server
ralph status

Can I script Ralph operations?

Yes, use --json flag for programmatic access:

#!/bin/bash

# Start session
ralph run 10 -b

# Wait for completion
while true; do
  STATUS=$(ralph status --json | jq -r '.state')
  if [ "$STATUS" = "complete" ]; then
    break
  fi
  sleep 60
done

# Get results
ralph task list --json > results.json
ralph progress --json > progress.json

# Send notification
curl -X POST https://hooks.slack.com/... \
  -d "{\"text\": \"Ralph session complete!\"}"

How do I backup my Ralph data?

Backup the entire Ralph directory:

# Backup
tar -czf ralph-backup.tar.gz ~/.ralph

# Restore
tar -xzf ralph-backup.tar.gz -C ~/

Or backup specific project:

# Backup project
tar -czf project-backup.tar.gz ~/.ralph/projects/my-project

# Restore project
tar -xzf project-backup.tar.gz -C ~/.ralph/projects/

Can I use Ralph with Docker?

Yes, create a Dockerfile:

FROM oven/bun:latest

# Install Ralph
RUN curl -fsSL https://raw.githubusercontent.com/nitodeco/ralph/main/scripts/install.sh | bash

# Install your AI agent
RUN curl -fsSL https://cursor.sh/install | bash

# Set working directory
WORKDIR /app

# Copy project
COPY . .

# Run Ralph
CMD ["ralph", "run"]

Build and run:

docker build -t my-ralph-project .
docker run -v ~/.ralph:/root/.ralph my-ralph-project

Contributing

How do I contribute to Ralph?

  1. Fork the repository: github.com/nitodeco/ralph

  2. Set up development environment:

    git clone https://github.com/your-username/ralph.git
cd ralph
bun install

  3. Make changes and test:

    bun run dev
bun test

  4. Submit a pull request

See Contributing Guide for detailed instructions.

How do I report bugs?

Open an issue on GitHub with:

  • Ralph version: ralph --version
  • Agent being used: From ralph config
  • Operating system: uname -a
  • Steps to reproduce: What you did before the error
  • Expected behavior: What should have happened
  • Actual behavior: What actually happened
  • Error message: Full error text
  • Logs: Relevant log excerpts

Can I request features?

Yes! Open a feature request on GitHub Issues with:

  • Clear description of the feature
  • Use case (why you need it)
  • Proposed implementation (if you have ideas)

Getting Help

Where can I get help?

  1. Documentation: docs.ralph.dev
  2. FAQ: This page
  3. GitHub Issues: github.com/nitodeco/ralph/issues
  4. Troubleshooting Guide: /docs/troubleshooting/common-issues/

How do I stay updated?

Is there a community?

  • GitHub Discussions: Ask questions and share experiences
  • GitHub Issues: Report bugs and request features
  • Discord: (Link if available)

More Questions?

If your question isn’t answered here:

  1. Search the docs: /docs/
  2. Check troubleshooting: /docs/troubleshooting/common-issues/
  3. Search GitHub Issues: github.com/nitodeco/ralph/issues
  4. Ask a question: Open a new issue or discussion