My Ralph Wiggum setup, an autonomous bash script that runs Claude Code, Codex, OpenCode, Cursor agent, Qwen & Droid in a loop until your PRD is complete.
# Add to your Claude Code skills
git clone https://github.com/michaelshimeles/ralphyJoin our Discord - Questions? Want to contribute? Join the community!

Autonomous AI coding loop. Runs AI agents on tasks until done.
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.
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
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"
No comments yet. Be the first to share your thoughts!
Rules apply to all tasks (single or PRD).
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
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
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.
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
JSON:
ralphy --json PRD.json
{
"tasks": [
{
"title": "create auth",
"completed": false,
"parallel_group": 1,
"description": "Optional details"
}
]
}
Titles must be unique.
GitHub Issues:
ralphy --github owner/repo
ralphy --github owner/repo --github-label "ready"
ralphy --parallel # 3 agents default
ralphy --parallel --max-parallel 5 # 5 agents
Each agent gets isolated worktree + branch:
Agent 1 → /tmp/xxx/agent-1 → ralphy/agent-1-create-auth
Agent 2 → /tmp/xxx/agent-2 → ralphy/agent-2-add-dashboard
Agent 3 → /tmp/xxx/agent-3 → ralphy/agent-3-build-api
Without --create-pr: auto-merges back to base branch, AI resolves conflicts.
With --create-pr: keeps branches, creates PRs.
With --no-merge: keeps branches without merging or creating PRs.
YAML parallel groups - control execution order:
tasks:
- title: Create User model
parallel_group: 1
- title: Create Post model
parallel_group: 1 # same group = runs together
- title: Add relationships
parallel_group: 2 # runs after group 1
ralphy --branch-per-task # branch per task
ralphy --branch-per-task --create-pr # + create PRs
ralphy --branch-per-task --draft-pr # + draft PRs
ralphy --base-branch main # branch from main
Branch naming: ralphy/<task-slug>
Ralphy can use agent-browser to automate browser interactions during tasks.
ralphy "test the login flow" --browser # force enable
ralphy "add checkout" --no-browser # force disable
ralphy "build feature" # auto-detect (default)
When enabled, the AI gets browser commands:
agent-browser open <url> - navigate to URLagent-browser snapshot - get element refs (@e1, @e2)agent-browser click @e1 - click elementagent-browser type @e1 "text" - type into inputagent-browser screenshot <file> - capture screenshotUse cases:
Config (.ralphy/config.yaml):
capabilities:
browser: "auto" # "auto", "true", or "false"
Get notified when sessions complete via Discord, Slack, or custom webhooks.
Config (.ralphy/config.yaml):
notifications:
discord_webhook: "https://discord.com/api/webhooks/..."
slack_webhook: "https://hooks.slack.com/services/..."
custom_webhook: "https://your-api.com/webhook"
Notifications include task completion counts and status (completed/failed).
For large repos with big dependency directories, sandbox mode is faster than git worktrees:
ralphy --parallel --sandbox
How it works:
node_modules, .git, vendor, .venv, .pnpm-store, .yarn, .cache)src/, app/, lib/, config files, etc.)Why use it:
node_modules across worktreesWhen to use worktrees instead (default):
git commands that require a real repoParallel execution reliability:
.ralphy/progress.txt, .ralphy-worktrees, or .ralphy-sandboxes| Flag | What it does |
|------|--------------|
| --prd PATH | task file or folder (auto-detected, default: PRD.md) |
| --yaml FILE | YAML task file |
| --json FILE | JSON task file |
| --github REPO | use GitHub issues |
| --github-label TAG | filter issues by label |
| --sync-issue N | sync PRD progress to GitHub issue #N |
| --model NAME | override model for any engine |
| --sonnet | shortcut for --claude --model sonnet |
| --parallel | run parallel |
| --max-parallel N | max agents (default: 3) |
| --sandbox | use lightweight sandboxes instead of git worktrees |
| --no-merge | skip auto-merge in parallel mode |
| --branch-per-task | branch per task |
| --base-branch NAME | base branch |
| --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 |
| --max-iterations N | stop after N tasks |
| --max-retries N | retries per task (default: 3) |
| --retry-delay N | seconds between retries |
| --dry-run | preview only |
| --browser | enable browser automation |
| --no-browser | disable browser automation |
| -v, --verbose | debug output |
| --init | setup .ralphy/ config |
| --config | show config |
| --add-rule "rule" | add rule to config |
Required:
npm version (ralphy-cli):
Bash version (ralphy.sh):
jqyq (optional, for YAML tasks)bc (optional, for cost calc)Both versions:
gh (optional, for GitHub issues / --create-pr)--browser)| Engine | CLI | Permissions | Output |
|--------|-----|-------------|--------|
| Claude | claude | --dangerously-skip-permissions | tokens + cost |
| OpenCode | opencode | full-auto | tokens + cost |
| Codex | codex | N/A | tokens |
| Cursor | agent | --force | duration |
| Qwen | qwen | --approval-mode yolo | tokens |
| Droid | droid exec | --auto medium | duration |
| Copilot | copilot | --yolo | tokens |
| Gemini | gemini | `-