npm version

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

Ralphy

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"

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 URL
• agent-browser snapshot - get element refs (@e1, @e2)
• agent-browser click @e1 - click element
• agent-browser type @e1 "text" - type into input
• agent-browser screenshot <file> - capture screenshot

Use cases:

• Testing UI after implementing features
• Verifying deployments
• Form filling and workflow testing

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:

• Symlinks read-only dependencies (node_modules, .git, vendor, .venv, .pnpm-store, .yarn, .cache)
• Copies source files that agents might modify (src/, app/, lib/, config files, etc.)

Why use it:

• Avoids duplicating gigabytes of node_modules across worktrees
• Much faster sandbox creation for large monorepos
• Changes sync back to original directory after each task

When to use worktrees instead (default):

• Need full git history access in each sandbox
• Running git commands that require a real repo
• Smaller repos where worktree overhead is minimal

Parallel execution reliability:

• If worktree operations fail (e.g., nested worktree repos), ralphy falls back to sandbox mode automatically
• Retryable rate-limit or quota errors are detected and deferred for later retry
• Local changes are stashed before the merge phase and restored after
• Agents should not modify PRD files, .ralphy/progress.txt, .ralphy-worktrees, or .ralphy-sandboxes

Required:

• AI CLI: Claude Code, OpenCode, Cursor, Codex, Qwen-Code, Factory Droid, GitHub Copilot, or Gemini CLI

npm version (ralphy-cli):

• Node.js 18+ or Bun

Bash version (ralphy.sh):

• jq
• yq (optional, for YAML tasks)
• bc (optional, for cost calc)

Both versions:

• gh (optional, for GitHub issues / --create-pr)
• agent-browser (optional, for --browser)

When an engine exits non-zero, ralphy includes the last lines of CLI output in the error message to make debugging easier.

• Improved auth error detection: simplified extractAuthenticationError function with better edge case handling (e.g., JSON dumps during login)
• Added project standards: CLAUDE.md, .cursorrules, CONTRIBUTING.md for consistent AI-assisted development
• Enhanced default prompts: enforce concise, focused code changes

• Copilot engine improvements: non-interactive mode (--yolo), proper error detection for auth/rate-limit/network errors, token usage parsing, temp file-based prompts for markdown preservation
• Fixed infinite retry loop: tasks now properly abort on fatal configuration/authentication errors
• Project standards: added .editorconfig and .gitattributes for consistent coding styles

• JSON PRD support: new --json flag to use JSON files as task sources with support for parallel groups and task descriptions

• Gemini CLI support: new --gemini engine option for Google Gemini CLI
• GitHub issue sync: --sync-issue <number> syncs PRD progress to a GitHub issue after each task
• performance improvements: reduced redundant file reads, exponential backoff for retries, non-blocking logging, operation timing visibility
• version fix: CLI version now reads dynamically from package.json

• parallel reliability: fallback to sandbox mode on worktree errors
• error output: include CLI output snippet for failed engine commands
• retry handling: detect rate-limit/quota errors and stop early
• merge safety: stash local changes before merge phase and restore after
• prompts: explicitly avoid PRD and .ralphy progress/sandbox/worktree edits

• sandbox mode: lightweight isolation using symlinks for dependencies (faster than worktrees)
• performance improvements: task caching, parallel merge analysis, smart branch ordering
• webhook notifications: Discord, Slack, and custom webhooks for session completion (configure in .ralphy/config.yaml)
• engine-specific arguments: pass arguments to underlying CLI via -- separator
• Windows improvements: better error handling for .cmd wrappers

• Windows line ending handling fixes
• Windows Bun command resolution fixes

• GitHub Copilot CLI support (--copilot)

• model override: --model <name> flag to override model for any engine
• --sonnet shortcut for --claude --model sonnet
• --no-merge flag to skip auto-merge in parallel mode
• AI-assisted merge conflict resolution during parallel auto-merge
• root user detection: error for Claude/Cursor, warning for other engines
• improved OpenCode error handling and model override support

• browser automation: --browser / --no-browser with agent-browser
• auto-detects agent-browser when available
• config option: capabilities.browser in .ralphy/config.yaml

• TypeScript CLI: npm install -g ralphy-cli
• cross-platform binaries (macOS, Linux, Windows)
• no dependencies on jq/yq/bc for npm version

• single-task mode: ralphy "task" without PRD
• project config: --init creates .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

See CONTRIBUTING.md for development guidelines.

Key principles:

• Keep changes small and focused - one logical change per commit
• Break large tasks into micro-tasks
• Quality over speed
• Don't leave dead code
• Fight entropy - leave the codebase better than you found it

AI coding assistants can reference:

• CLAUDE.md - Claude Code instructions
• .cursorrules - Cursor IDE rules

• Discord

MIT