[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-74830":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":10,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":22,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":30,"readmeContent":31,"aiSummary":32,"trendingCount":16,"starSnapshotCount":16,"syncStatus":33,"lastSyncTime":34,"discoverSource":35},74830,"ralphy","michaelshimeles\u002Fralphy","michaelshimeles","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.","https:\u002F\u002Fralphy.goshen.fyi",null,"TypeScript",2887,358,35,26,0,3,11,39,9,72.07,false,"main",true,[26,27,28,29,5],"claude-code","opencode","ralph-loop","ralph-wiggum","2026-06-12 04:01:16","# Ralphy\n\n[![npm version](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fralphy-cli.svg)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fralphy-cli)\n\n**[Join our Discord](https:\u002F\u002Fdiscord.gg\u002FSZZV74mCuV)** - Questions? Want to contribute? Join the community!\n\n![Ralphy](assets\u002Fralphy.jpeg)\n\nAutonomous AI coding loop. Runs AI agents on tasks until done.\n\n## Install\n\n**Option A: [npm](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fralphy-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:\u002F\u002Fgithub.com\u002Fmichaelshimeles\u002Fralphy.git\ncd ralphy && chmod +x ralphy.sh\n\n.\u002Fralphy.sh \"add login button\"\n.\u002Fralphy.sh --prd PRD.md\n```\n\nBoth versions have identical features. Examples below use `ralphy` (npm) - substitute `.\u002Fralphy.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\u002Fconfig.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\u002Futils\u002Ferrors.ts\"\n\nboundaries:\n  never_touch:\n    - \"src\u002Flegacy\u002F**\"\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\u002Fglm-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 .\u002Fprd\u002F\n```\nWhen pointing to a folder, Ralphy reads all `.md` files and aggregates tasks:\n```\nprd\u002F\n  backend.md      # - [ ] create user API\n  frontend.md     # - [ ] add login page\n  infra.md        # - [ ] setup CI\u002FCD\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\u002Frepo\nralphy --github owner\u002Frepo --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 → \u002Ftmp\u002Fxxx\u002Fagent-1 → ralphy\u002Fagent-1-create-auth\nAgent 2 → \u002Ftmp\u002Fxxx\u002Fagent-2 → ralphy\u002Fagent-2-add-dashboard\nAgent 3 → \u002Ftmp\u002Fxxx\u002Fagent-3 → ralphy\u002Fagent-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\u002F\u003Ctask-slug>`\n\n## Browser Automation\n\nRalphy can use [agent-browser](https:\u002F\u002Fagent-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>` - 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>` - 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\u002Fconfig.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\u002Fconfig.yaml`):\n```yaml\nnotifications:\n  discord_webhook: \"https:\u002F\u002Fdiscord.com\u002Fapi\u002Fwebhooks\u002F...\"\n  slack_webhook: \"https:\u002F\u002Fhooks.slack.com\u002Fservices\u002F...\"\n  custom_webhook: \"https:\u002F\u002Fyour-api.com\u002Fwebhook\"\n```\n\nNotifications include task completion counts and status (completed\u002Ffailed).\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\u002F`, `app\u002F`, `lib\u002F`, 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\u002Fprogress.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\u002F 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:\u002F\u002Fgithub.com\u002Fanthropics\u002Fclaude-code), [OpenCode](https:\u002F\u002Fopencode.ai\u002Fdocs\u002F), [Cursor](https:\u002F\u002Fcursor.com), Codex, Qwen-Code, [Factory Droid](https:\u002F\u002Fdocs.factory.ai\u002Fcli\u002Fgetting-started\u002Fquickstart), [GitHub Copilot](https:\u002F\u002Fdocs.github.com\u002Fen\u002Fcopilot\u002Fhow-tos\u002Fuse-copilot-agents\u002Fuse-copilot-cli), or [Gemini CLI](https:\u002F\u002Fgithub.com\u002Fgoogle-gemini\u002Fgemini-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 \u002F `--create-pr`)\n- [agent-browser](https:\u002F\u002Fagent-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\u002FA | 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\u002Frate-limit\u002Fnetwork errors, token usage parsing, temp file-based prompts for markdown preservation\n- **Fixed infinite retry loop**: tasks now properly abort on fatal configuration\u002Fauthentication 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>` 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\u002Fquota errors and stop early\n- merge safety: stash local changes before merge phase and restore after\n- prompts: explicitly avoid PRD and `.ralphy` progress\u002Fsandbox\u002Fworktree 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\u002Fconfig.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>` 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\u002FCursor, warning for other engines\n- improved OpenCode error handling and model override support\n\n### v4.2.0\n- browser automation: `--browser` \u002F `--no-browser` with [agent-browser](https:\u002F\u002Fagent-browser.dev)\n- auto-detects agent-browser when available\n- config option: `capabilities.browser` in `.ralphy\u002Fconfig.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\u002Fyq\u002Fbc for npm version\n\n### v4.0.0\n- single-task mode: `ralphy \"task\"` without PRD\n- project config: `--init` creates `.ralphy\u002F` 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:\u002F\u002Frasmic.link\u002Fdiscord)\n\n## License\n\nMIT\n","Ralphy 是一个自动化 AI 编码循环工具，能够运行多种 AI 代理（如 Claude Code、Codex、OpenCode、Cursor agent、Qwen 和 Droid）来完成编程任务直到 PRD 完成。其核心功能包括通过命令行执行单个任务或处理整个 PRD 文档中的任务列表，并支持自定义项目配置和规则以指导 AI 的行为。此外，用户可以选择不同的 AI 引擎，并为每个引擎指定特定的模型或参数。此工具特别适合需要快速迭代开发流程的开发者，尤其是在有明确需求文档的情况下，可以显著提高编码效率。",2,"2026-06-11 03:51:01","high_star"]