Autonomous AI coding loop. Runs AI agents on tasks until done.
git clone https://github.com/michaelshimeles/ralphy.git
cd ralphy && chmod +x ralphy.sh
# Single task
./ralphy.sh "add login button"
# Or use a task list
./ralphy.sh --prd PRD.mdSingle task - just tell it what to do:
./ralphy.sh "add dark mode"
./ralphy.sh "fix the auth bug"Task list - work through a PRD:
./ralphy.sh # uses PRD.md
./ralphy.sh --prd tasks.mdOptional. Stores rules the AI must follow.
./ralphy.sh --init # auto-detects project settings
./ralphy.sh --config # view config
./ralphy.sh --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).
./ralphy.sh # Claude Code (default)
./ralphy.sh --opencode # OpenCode
./ralphy.sh --cursor # Cursor
./ralphy.sh --codex # Codex
./ralphy.sh --qwen # Qwen-Code
./ralphy.sh --droid # Factory DroidMarkdown (default):
./ralphy.sh --prd PRD.md## Tasks
- [ ] create auth
- [ ] add dashboard
- [x] done task (skipped)YAML:
./ralphy.sh --yaml tasks.yamltasks:
- title: create auth
completed: false
- title: add dashboard
completed: falseGitHub Issues:
./ralphy.sh --github owner/repo
./ralphy.sh --github owner/repo --github-label "ready"./ralphy.sh --parallel # 3 agents default
./ralphy.sh --parallel --max-parallel 5 # 5 agentsEach 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, AI resolves conflicts.
With --create-pr: keeps branches, creates 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.sh --branch-per-task # branch per task
./ralphy.sh --branch-per-task --create-pr # + create PRs
./ralphy.sh --branch-per-task --draft-pr # + draft PRs
./ralphy.sh --base-branch main # branch from mainBranch naming: ralphy/<task-slug>
| Flag | What it does |
|---|---|
--prd FILE |
task file (default: PRD.md) |
--yaml FILE |
YAML task file |
--github REPO |
use GitHub issues |
--github-label TAG |
filter issues by label |
--parallel |
run parallel |
--max-parallel N |
max agents (default: 3) |
--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 |
-v, --verbose |
debug output |
--init |
setup .ralphy/ config |
--config |
show config |
--add-rule "rule" |
add rule to config |
Required:
- AI CLI: Claude Code, OpenCode, Cursor, Codex, Qwen-Code, or Factory Droid
jq
Optional:
yq- for YAML tasksgh- for GitHub issues /--create-prbc- for cost calc
| 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 |
- single-task mode:
ralphy "task"without PRD - project config:
--initcreates.ralphy/with rules + auto-detection - new:
--config,--add-rule,--no-commit
- Factory Droid support (
--droid)
- Qwen-Code support (
--qwen)
- Cursor support (
--cursor) - better task verification
- parallel execution with worktrees
- branch-per-task + auto-PR
- YAML + GitHub Issues sources
- parallel groups
- OpenCode support
- retry logic
--max-iterations,--dry-run
- initial release
MIT