{"id":47004612,"url":"https://github.com/michaelshimeles/ralphy","last_synced_at":"2026-05-01T22:36:42.244Z","repository":{"id":332858951,"uuid":"1135260262","full_name":"michaelshimeles/ralphy","owner":"michaelshimeles","description":"My Ralph Wiggum setup, an autonomous bash script that runs Claude Code, Codex, OpenCode, Cursor agent, Qwen \u0026 Droid in a loop until your PRD is complete.","archived":false,"fork":false,"pushed_at":"2026-02-05T16:28:20.000Z","size":3427,"stargazers_count":2513,"open_issues_count":37,"forks_count":313,"subscribers_count":29,"default_branch":"main","last_synced_at":"2026-03-05T07:43:14.033Z","etag":null,"topics":["claude-code","opencode","ralph-loop","ralph-wiggum","ralphy"],"latest_commit_sha":null,"homepage":"https://ralphy.goshen.fyi","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/michaelshimeles.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-15T21:23:21.000Z","updated_at":"2026-03-05T00:54:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/michaelshimeles/ralphy","commit_stats":null,"previous_names":["michaelshimeles/ralphy"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/michaelshimeles/ralphy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michaelshimeles%2Fralphy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michaelshimeles%2Fralphy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michaelshimeles%2Fralphy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michaelshimeles%2Fralphy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/michaelshimeles","download_url":"https://codeload.github.com/michaelshimeles/ralphy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michaelshimeles%2Fralphy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30415037,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T00:40:14.898Z","status":"online","status_checked_at":"2026-03-12T02:00:07.260Z","response_time":114,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","opencode","ralph-loop","ralph-wiggum","ralphy"],"created_at":"2026-03-11T20:00:29.727Z","updated_at":"2026-03-12T04:01:04.145Z","avatar_url":"https://github.com/michaelshimeles.png","language":"TypeScript","funding_links":[],"categories":["Autonomous Loop Runners","Resources","Multi-Agent Systems","Implementations"],"sub_categories":["Project-Specific Commands","Parallel Processing"],"readme":"# Ralphy\n\n[![npm version](https://img.shields.io/npm/v/ralphy-cli.svg)](https://www.npmjs.com/package/ralphy-cli)\n\n**[Join our Discord](https://discord.gg/SZZV74mCuV)** - Questions? Want to contribute? Join the community!\n\n![Ralphy](assets/ralphy.jpeg)\n\nAutonomous AI coding loop. Runs AI agents on tasks until done.\n\n## Install\n\n**Option A: [npm](https://www.npmjs.com/package/ralphy-cli)** (recommended)\n```bash\nnpm install -g ralphy-cli\n\n# Then use anywhere\nralphy \"add login button\"\nralphy --prd PRD.md\n```\n\n**Option B: Clone**\n```bash\ngit clone https://github.com/michaelshimeles/ralphy.git\ncd ralphy \u0026\u0026 chmod +x ralphy.sh\n\n./ralphy.sh \"add login button\"\n./ralphy.sh --prd PRD.md\n```\n\nBoth versions have identical features. Examples below use `ralphy` (npm) - substitute `./ralphy.sh` if using the bash script.\n\n## Two Modes\n\n**Single task** - just tell it what to do:\n```bash\nralphy \"add dark mode\"\nralphy \"fix the auth bug\"\n```\n\n**Task list** - work through a PRD:\n```bash\nralphy              # uses PRD.md\nralphy --prd tasks.md\n```\n\n## Project Config\n\nOptional. Stores rules the AI must follow.\n\n```bash\nralphy --init              # auto-detects project settings\nralphy --config            # view config\nralphy --add-rule \"use TypeScript strict mode\"\n```\n\nCreates `.ralphy/config.yaml`:\n```yaml\nproject:\n  name: \"my-app\"\n  language: \"TypeScript\"\n  framework: \"Next.js\"\n\ncommands:\n  test: \"npm test\"\n  lint: \"npm run lint\"\n  build: \"npm run build\"\n\nrules:\n  - \"use server actions not API routes\"\n  - \"follow error pattern in src/utils/errors.ts\"\n\nboundaries:\n  never_touch:\n    - \"src/legacy/**\"\n    - \"*.lock\"\n```\n\nRules apply to all tasks (single or PRD).\n\n## AI Engines\n\n```bash\nralphy              # Claude Code (default)\nralphy --opencode   # OpenCode\nralphy --cursor     # Cursor\nralphy --codex      # Codex\nralphy --qwen       # Qwen-Code\nralphy --droid      # Factory Droid\nralphy --copilot    # GitHub Copilot\nralphy --gemini     # Gemini CLI\n```\n\n### Model Override\n\nOverride the default model for any engine:\n\n```bash\nralphy --model sonnet \"add feature\"                    # use sonnet with Claude\nralphy --sonnet \"add feature\"                          # shortcut for above\nralphy --opencode --model opencode/glm-4.7-free \"task\" # custom OpenCode model\nralphy --qwen --model qwen-max \"build api\"             # custom Qwen model\n```\n\n### Engine-Specific Arguments\n\nPass additional arguments to the underlying engine CLI using `--` separator:\n\n```bash\n# Pass copilot-specific arguments\nralphy --copilot --model \"claude-opus-4.5\" --prd PRD.md -- --allow-all-tools --allow-all-urls --stream on\n\n# Pass claude-specific arguments  \nralphy --claude \"add feature\" -- --no-permissions-prompt\n\n# Works with any engine\nralphy --cursor \"fix bug\" -- --custom-arg value\n```\n\nEverything after `--` is passed directly to the engine CLI without interpretation.\n\n## Task Sources\n\n**Markdown file** (default):\n```bash\nralphy --prd PRD.md\n```\n```markdown\n## Tasks\n- [ ] create auth\n- [ ] add dashboard\n- [x] done task (skipped)\n```\n\n**Markdown folder** (for large projects):\n```bash\nralphy --prd ./prd/\n```\nWhen pointing to a folder, Ralphy reads all `.md` files and aggregates tasks:\n```\nprd/\n  backend.md      # - [ ] create user API\n  frontend.md     # - [ ] add login page\n  infra.md        # - [ ] setup CI/CD\n```\nTasks are tracked per-file so completion updates the correct file.\n\n**YAML**:\n```bash\nralphy --yaml tasks.yaml\n```\n```yaml\ntasks:\n  - title: create auth\n    completed: false\n  - title: add dashboard\n    completed: false\n```\n\n**JSON**:\n```bash\nralphy --json PRD.json\n```\n```json\n{\n  \"tasks\": [\n    {\n      \"title\": \"create auth\",\n      \"completed\": false,\n      \"parallel_group\": 1,\n      \"description\": \"Optional details\"\n    }\n  ]\n}\n```\nTitles must be unique.\n\n**GitHub Issues**:\n```bash\nralphy --github owner/repo\nralphy --github owner/repo --github-label \"ready\"\n```\n\n## Parallel Execution\n\n```bash\nralphy --parallel                  # 3 agents default\nralphy --parallel --max-parallel 5 # 5 agents\n```\n\nEach agent gets isolated worktree + branch:\n```\nAgent 1 → /tmp/xxx/agent-1 → ralphy/agent-1-create-auth\nAgent 2 → /tmp/xxx/agent-2 → ralphy/agent-2-add-dashboard\nAgent 3 → /tmp/xxx/agent-3 → ralphy/agent-3-build-api\n```\n\nWithout `--create-pr`: auto-merges back to base branch, AI resolves conflicts.\nWith `--create-pr`: keeps branches, creates PRs.\nWith `--no-merge`: keeps branches without merging or creating PRs.\n\n**YAML parallel groups** - control execution order:\n```yaml\ntasks:\n  - title: Create User model\n    parallel_group: 1\n  - title: Create Post model\n    parallel_group: 1  # same group = runs together\n  - title: Add relationships\n    parallel_group: 2  # runs after group 1\n```\n\n## Branch Workflow\n\n```bash\nralphy --branch-per-task                # branch per task\nralphy --branch-per-task --create-pr    # + create PRs\nralphy --branch-per-task --draft-pr     # + draft PRs\nralphy --base-branch main               # branch from main\n```\n\nBranch naming: `ralphy/\u003ctask-slug\u003e`\n\n## Browser Automation\n\nRalphy can use [agent-browser](https://agent-browser.dev) to automate browser interactions during tasks.\n\n```bash\nralphy \"test the login flow\" --browser    # force enable\nralphy \"add checkout\" --no-browser        # force disable\nralphy \"build feature\"                    # auto-detect (default)\n```\n\nWhen enabled, the AI gets browser commands:\n- `agent-browser open \u003curl\u003e` - navigate to URL\n- `agent-browser snapshot` - get element refs (@e1, @e2)\n- `agent-browser click @e1` - click element\n- `agent-browser type @e1 \"text\"` - type into input\n- `agent-browser screenshot \u003cfile\u003e` - capture screenshot\n\n**Use cases:**\n- Testing UI after implementing features\n- Verifying deployments\n- Form filling and workflow testing\n\n**Config** (`.ralphy/config.yaml`):\n```yaml\ncapabilities:\n  browser: \"auto\"  # \"auto\", \"true\", or \"false\"\n```\n\n## Webhook Notifications\n\nGet notified when sessions complete via Discord, Slack, or custom webhooks.\n\n**Config** (`.ralphy/config.yaml`):\n```yaml\nnotifications:\n  discord_webhook: \"https://discord.com/api/webhooks/...\"\n  slack_webhook: \"https://hooks.slack.com/services/...\"\n  custom_webhook: \"https://your-api.com/webhook\"\n```\n\nNotifications include task completion counts and status (completed/failed).\n\n## Sandbox Mode\n\nFor large repos with big dependency directories, sandbox mode is faster than git worktrees:\n\n```bash\nralphy --parallel --sandbox\n```\n\n**How it works:**\n- **Symlinks** read-only dependencies (`node_modules`, `.git`, `vendor`, `.venv`, `.pnpm-store`, `.yarn`, `.cache`)\n- **Copies** source files that agents might modify (`src/`, `app/`, `lib/`, config files, etc.)\n\n**Why use it:**\n- Avoids duplicating gigabytes of `node_modules` across worktrees\n- Much faster sandbox creation for large monorepos\n- Changes sync back to original directory after each task\n\n**When to use worktrees instead (default):**\n- Need full git history access in each sandbox\n- Running `git` commands that require a real repo\n- Smaller repos where worktree overhead is minimal\n\n**Parallel execution reliability:**\n- If worktree operations fail (e.g., nested worktree repos), ralphy falls back to sandbox mode automatically\n- Retryable rate-limit or quota errors are detected and deferred for later retry\n- Local changes are stashed before the merge phase and restored after\n- Agents should not modify PRD files, `.ralphy/progress.txt`, `.ralphy-worktrees`, or `.ralphy-sandboxes`\n\n## Options\n\n| Flag | What it does |\n|------|--------------|\n| `--prd PATH` | task file or folder (auto-detected, default: PRD.md) |\n| `--yaml FILE` | YAML task file |\n| `--json FILE` | JSON task file |\n| `--github REPO` | use GitHub issues |\n| `--github-label TAG` | filter issues by label |\n| `--sync-issue N` | sync PRD progress to GitHub issue #N |\n| `--model NAME` | override model for any engine |\n| `--sonnet` | shortcut for `--claude --model sonnet` |\n| `--parallel` | run parallel |\n| `--max-parallel N` | max agents (default: 3) |\n| `--sandbox` | use lightweight sandboxes instead of git worktrees |\n| `--no-merge` | skip auto-merge in parallel mode |\n| `--branch-per-task` | branch per task |\n| `--base-branch NAME` | base branch |\n| `--create-pr` | create PRs |\n| `--draft-pr` | draft PRs |\n| `--no-tests` | skip tests |\n| `--no-lint` | skip lint |\n| `--fast` | skip tests + lint |\n| `--no-commit` | don't auto-commit |\n| `--max-iterations N` | stop after N tasks |\n| `--max-retries N` | retries per task (default: 3) |\n| `--retry-delay N` | seconds between retries |\n| `--dry-run` | preview only |\n| `--browser` | enable browser automation |\n| `--no-browser` | disable browser automation |\n| `-v, --verbose` | debug output |\n| `--init` | setup .ralphy/ config |\n| `--config` | show config |\n| `--add-rule \"rule\"` | add rule to config |\n\n## Requirements\n\n**Required:**\n- AI CLI: [Claude Code](https://github.com/anthropics/claude-code), [OpenCode](https://opencode.ai/docs/), [Cursor](https://cursor.com), Codex, Qwen-Code, [Factory Droid](https://docs.factory.ai/cli/getting-started/quickstart), [GitHub Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli), or [Gemini CLI](https://github.com/google-gemini/gemini-cli)\n\n**npm version (`ralphy-cli`):**\n- Node.js 18+ or Bun\n\n**Bash version (`ralphy.sh`):**\n- `jq`\n- `yq` (optional, for YAML tasks)\n- `bc` (optional, for cost calc)\n\n**Both versions:**\n- `gh` (optional, for GitHub issues / `--create-pr`)\n- [agent-browser](https://agent-browser.dev) (optional, for `--browser`)\n\n## Engine Details\n\n| Engine | CLI | Permissions | Output |\n|--------|-----|-------------|--------|\n| Claude | `claude` | `--dangerously-skip-permissions` | tokens + cost |\n| OpenCode | `opencode` | `full-auto` | tokens + cost |\n| Codex | `codex` | N/A | tokens |\n| Cursor | `agent` | `--force` | duration |\n| Qwen | `qwen` | `--approval-mode yolo` | tokens |\n| Droid | `droid exec` | `--auto medium` | duration |\n| Copilot | `copilot` | `--yolo` | tokens |\n| Gemini | `gemini` | `--yolo` | tokens + cost |\n\nWhen an engine exits non-zero, ralphy includes the last lines of CLI output in the error message to make debugging easier.\n\n---\n\n## Changelog\n\n### v4.7.2\n- **Improved auth error detection**: simplified `extractAuthenticationError` function with better edge case handling (e.g., JSON dumps during login)\n- **Added project standards**: `CLAUDE.md`, `.cursorrules`, `CONTRIBUTING.md` for consistent AI-assisted development\n- **Enhanced default prompts**: enforce concise, focused code changes\n\n### v4.7.1\n- **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\n- **Fixed infinite retry loop**: tasks now properly abort on fatal configuration/authentication errors\n- **Project standards**: added `.editorconfig` and `.gitattributes` for consistent coding styles\n\n### v4.7.0\n- **JSON PRD support**: new `--json` flag to use JSON files as task sources with support for parallel groups and task descriptions\n\n### v4.6.0\n- **Gemini CLI support**: new `--gemini` engine option for Google Gemini CLI\n- **GitHub issue sync**: `--sync-issue \u003cnumber\u003e` syncs PRD progress to a GitHub issue after each task\n- **performance improvements**: reduced redundant file reads, exponential backoff for retries, non-blocking logging, operation timing visibility\n- **version fix**: CLI version now reads dynamically from package.json\n\n### v4.5.3\n- parallel reliability: fallback to sandbox mode on worktree errors\n- error output: include CLI output snippet for failed engine commands\n- retry handling: detect rate-limit/quota errors and stop early\n- merge safety: stash local changes before merge phase and restore after\n- prompts: explicitly avoid PRD and `.ralphy` progress/sandbox/worktree edits\n\n### v4.5.0\n- **sandbox mode**: lightweight isolation using symlinks for dependencies (faster than worktrees)\n- **performance improvements**: task caching, parallel merge analysis, smart branch ordering\n- **webhook notifications**: Discord, Slack, and custom webhooks for session completion (configure in `.ralphy/config.yaml`)\n- **engine-specific arguments**: pass arguments to underlying CLI via `--` separator\n- **Windows improvements**: better error handling for .cmd wrappers\n\n### v4.4.1\n- Windows line ending handling fixes\n- Windows Bun command resolution fixes\n\n### v4.4.0\n- GitHub Copilot CLI support (`--copilot`)\n\n### v4.3.0\n- model override: `--model \u003cname\u003e` flag to override model for any engine\n- `--sonnet` shortcut for `--claude --model sonnet`\n- `--no-merge` flag to skip auto-merge in parallel mode\n- AI-assisted merge conflict resolution during parallel auto-merge\n- root user detection: error for Claude/Cursor, warning for other engines\n- improved OpenCode error handling and model override support\n\n### v4.2.0\n- browser automation: `--browser` / `--no-browser` with [agent-browser](https://agent-browser.dev)\n- auto-detects agent-browser when available\n- config option: `capabilities.browser` in `.ralphy/config.yaml`\n\n### v4.1.0\n- TypeScript CLI: `npm install -g ralphy-cli`\n- cross-platform binaries (macOS, Linux, Windows)\n- no dependencies on jq/yq/bc for npm version\n\n### v4.0.0\n- single-task mode: `ralphy \"task\"` without PRD\n- project config: `--init` creates `.ralphy/` with rules + auto-detection\n- new: `--config`, `--add-rule`, `--no-commit`\n\n### v3.3.0\n- Factory Droid support (`--droid`)\n\n### v3.2.0\n- Qwen-Code support (`--qwen`)\n\n### v3.1.0\n- Cursor support (`--cursor`)\n- better task verification\n\n### v3.0.0\n- parallel execution with worktrees\n- branch-per-task + auto-PR\n- YAML + GitHub Issues sources\n- parallel groups\n\n### v2.0.0\n- OpenCode support\n- retry logic\n- `--max-iterations`, `--dry-run`\n\n### v1.0.0\n- initial release\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.\n\n**Key principles:**\n- Keep changes small and focused - one logical change per commit\n- Break large tasks into micro-tasks\n- Quality over speed\n- Don't leave dead code\n- Fight entropy - leave the codebase better than you found it\n\nAI coding assistants can reference:\n- [CLAUDE.md](CLAUDE.md) - Claude Code instructions\n- [.cursorrules](.cursorrules) - Cursor IDE rules\n\n## Community\n\n- [Discord](https://rasmic.link/discord)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichaelshimeles%2Fralphy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmichaelshimeles%2Fralphy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichaelshimeles%2Fralphy/lists"}