Ralphy

Join our Discord - Questions? Want to contribute? Join the community!

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

Install

Option A: npm (recommended)

npm install -g ralphy-cli

# Then use anywhere
ralphy "add login button"
ralphy --prd PRD.md

Option B: Clone

git clone https://github.com/michaelshimeles/ralphy.git
cd ralphy && chmod +x ralphy.sh

./ralphy.sh "add login button"
./ralphy.sh --prd PRD.md

Both versions have identical features. Examples below use ralphy (npm) - substitute ./ralphy.sh if using the bash script.

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"

Rules apply to all tasks (single or PRD).

AI Engines

ralphy              # Claude Code (default)
ralphy --opencode   # OpenCode
ralphy --cursor     # Cursor
ralphy --codex      # Codex
ralphy --qwen       # Qwen-Code
ralphy --droid      # Factory Droid
ralphy --copilot    # GitHub Copilot
ralphy --gemini     # Gemini CLI

Model Override

Override the default model for any engine:

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" # custom OpenCode model
ralphy --qwen --model qwen-max "build api"             # custom Qwen model

Engine-Specific Arguments

Pass additional arguments to the underlying engine CLI using -- separator:

# Pass copilot-specific arguments
ralphy --copilot --model "claude-opus-4.5" --prd PRD.md -- --allow-all-tools --allow-all-urls --stream on

# Pass claude-specific arguments  
ralphy --claude "add feature" -- --no-permissions-prompt

# Works with any engine
ralphy --cursor "fix bug" -- --custom-arg value

Everything after -- is passed directly to the engine CLI without interpretation.

Task Sources

Markdown file (default):

ralphy --prd PRD.md

## Tasks
- [ ] create auth
- [ ] add dashboard
- [x] done task (skipped)

Markdown folder (for large projects):

ralphy --prd ./prd/

When pointing to a folder, Ralphy reads all .md files and aggregates tasks:

prd/
  backend.md      # - [ ] create user API
  frontend.md     # - [ ] add login page
  infra.md        # - [ ] setup CI/CD

Tasks are tracked per-file so completion updates the correct file.

YAML:

ralphy --yaml tasks.yaml

tasks:
  - title: create auth
    completed: false
  - title: add dashboard
    completed: false