Ralphy

Autonomous AI coding loop. Runs AI agents on tasks until done.

Install

npm install -g ralphy-cli

Quick Start

# Single task
ralphy "add login button"

# Work through a task list
ralphy --prd PRD.md

Two Modes

Single task - just tell it what to do:

ralphy "add dark mode"
ralphy "fix the auth bug"

Task list - work through a PRD:

ralphy              # uses PRD.md
ralphy --prd tasks.md

Project Config

Optional. Stores rules the AI must follow.

ralphy --init              # auto-detects project settings
ralphy --config            # view config
ralphy --add-rule "use TypeScript strict mode"

Creates .ralphy/config.yaml:

project:
  name: "my-app"
  language: "TypeScript"
  framework: "Next.js"

commands:
  test: "npm test"
  lint: "npm run lint"
  build: "npm run build"

rules:
  - "use server actions not API routes"
  - "follow error pattern in src/utils/errors.ts"

boundaries:
  never_touch:
    - "src/legacy/**"
    - "*.lock"

AI Engines

ralphy              # Claude Code (default)
ralphy --opencode   # OpenCode
ralphy --cursor     # Cursor
ralphy --codex      # Codex
ralphy --qwen       # Qwen-Code
ralphy --droid      # Factory Droid

Model Override

ralphy --model sonnet "add feature"    # use sonnet with Claude
ralphy --sonnet "add feature"          # shortcut for above
ralphy --opencode --model opencode/glm-4.7-free "task"

Task Sources

Markdown file (default):

ralphy --prd PRD.md

Markdown folder (for large projects):

ralphy --prd ./prd/

Reads all .md files in the folder and aggregates tasks.

YAML:

ralphy --yaml tasks.yaml

GitHub Issues:

ralphy --github owner/repo
ralphy --github owner/repo --github-label "ready"

Parallel Execution

ralphy --parallel                  # 3 agents default
ralphy --parallel --max-parallel 5 # 5 agents

Each agent gets isolated worktree + branch. Without --create-pr: auto-merges back with AI conflict resolution. With --create-pr: keeps branches, creates PRs. With --no-merge: keeps branches without merging.

Branch Workflow

ralphy --branch-per-task                # branch per task
ralphy --branch-per-task --create-pr    # + create PRs
ralphy --branch-per-task --draft-pr     # + draft PRs

Browser Automation

Ralphy supports browser automation via agent-browser for testing web UIs.

ralphy "add login form" --browser    # enable browser automation
ralphy "fix checkout" --no-browser   # disable browser automation

When enabled (and agent-browser is installed), the AI can:

• Open URLs and navigate pages
• Click elements and fill forms
• Take screenshots for verification
• Test web UI changes after implementation

Options

| Flag | What it does | |------|--------------| | --prd PATH | task file or folder (auto-detected, default: PRD.md) | | --yaml FILE | YAML task file | | --github REPO | use GitHub issues | | --github-label TAG | filter issues by label | | --model NAME | override model for any engine | | --sonnet | shortcut for --claude --model sonnet | | --parallel | run parallel | | --max-parallel N | max agents (default: 3) | | --no-merge | skip auto-merge in parallel mode | | --branch-per-task | branch per task | | --base-branch BRANCH | base branch for PRs | | --create-pr | create PRs | | --draft-pr | draft PRs | | --no-tests | skip tests | | --no-lint | skip lint | | --fast | skip tests + lint | | --no-commit | don't auto-commit | | --browser | enable browser automation | | --no-browser | disable browser automation | | --max-iterations N | stop after N tasks | | --max-retries N | retries per task (default: 3) | | --retry-delay N | delay between retries in seconds (default: 5) | | --dry-run | preview only | | -v, --verbose | debug output | | --init | setup .ralphy/ config | | --config | show config | | --add-rule "rule" | add rule to config |

Requirements

• Node.js 18+ or Bun
• AI CLI: Claude Code, OpenCode, Cursor, Codex, Qwen-Code, or Factory Droid
• gh (optional, for GitHub issues / --create-pr)

Links

• GitHub
• Discord
• Bash script version

License

MIT