Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/michaelshimeles/ralphy

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://github.com/michaelshimeles/ralphy

claude-code opencode ralph-loop ralph-wiggum ralphy

Last synced: about 10 hours ago
JSON representation

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.

Awesome Lists containing this project

README 

          
# Ralphy



[![npm version](https://img.shields.io/npm/v/ralphy-cli.svg)](https://www.npmjs.com/package/ralphy-cli)



**[Join our Discord](https://discord.gg/SZZV74mCuV)** - Questions? Want to contribute? Join the community!



![Ralphy](assets/ralphy.jpeg)



Autonomous AI coding loop. Runs AI agents on tasks until done.



## Install



**Option A: [npm](https://www.npmjs.com/package/ralphy-cli)** (recommended)

```bash

npm install -g ralphy-cli



# Then use anywhere

ralphy "add login button"

ralphy --prd PRD.md

```



**Option B: Clone**

```bash

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.



## Two Modes



**Single task** - just tell it what to do:

```bash

ralphy "add dark mode"

ralphy "fix the auth bug"

```



**Task list** - work through a PRD:

```bash

ralphy              # uses PRD.md

ralphy --prd tasks.md

```



## Project Config



Optional. Stores rules the AI must follow.



```bash

ralphy --init              # auto-detects project settings

ralphy --config            # view config

ralphy --add-rule "use TypeScript strict mode"

```



Creates `.ralphy/config.yaml`:

```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).



## AI Engines



```bash

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

```



### Model Override



Override the default model for any engine:



```bash

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

```



### Engine-Specific Arguments



Pass additional arguments to the underlying engine CLI using `--` separator:



```bash

# 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.



## Task Sources



**Markdown file** (default):

```bash

ralphy --prd PRD.md

```

```markdown

## Tasks

- [ ] create auth

- [ ] add dashboard

- [x] done task (skipped)

```



**Markdown folder** (for large projects):

```bash

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**:

```bash

ralphy --yaml tasks.yaml

```

```yaml

tasks:

  - title: create auth

    completed: false

  - title: add dashboard

    completed: false

```



**JSON**:

```bash

ralphy --json PRD.json

```

```json

{

  "tasks": [

    {

      "title": "create auth",

      "completed": false,

      "parallel_group": 1,

      "description": "Optional details"

    }

  ]

}

```

Titles must be unique.



**GitHub Issues**:

```bash

ralphy --github owner/repo

ralphy --github owner/repo --github-label "ready"

```



## Parallel Execution



```bash

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:

```yaml

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

```



## Branch Workflow



```bash

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/`



## Browser Automation



Ralphy can use [agent-browser](https://agent-browser.dev) to automate browser interactions during tasks.



```bash

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 ` - 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 ` - capture screenshot



**Use cases:**

- Testing UI after implementing features

- Verifying deployments

- Form filling and workflow testing



**Config** (`.ralphy/config.yaml`):

```yaml

capabilities:

  browser: "auto"  # "auto", "true", or "false"

```



## Webhook Notifications



Get notified when sessions complete via Discord, Slack, or custom webhooks.



**Config** (`.ralphy/config.yaml`):

```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).



## Sandbox Mode



For large repos with big dependency directories, sandbox mode is faster than git worktrees:



```bash

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`



## Options



| 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 |



## Requirements



**Required:**

- 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)



**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](https://agent-browser.dev) (optional, for `--browser`)



## Engine Details



| 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` | `--yolo` | tokens + cost |



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



---



## Changelog



### v4.7.2

- **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



### v4.7.1

- **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



### v4.7.0

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



### v4.6.0

- **Gemini CLI support**: new `--gemini` engine option for Google Gemini CLI

- **GitHub issue sync**: `--sync-issue ` 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



### v4.5.3

- 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



### v4.5.0

- **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



### v4.4.1

- Windows line ending handling fixes

- Windows Bun command resolution fixes



### v4.4.0

- GitHub Copilot CLI support (`--copilot`)



### v4.3.0

- model override: `--model ` 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



### v4.2.0

- browser automation: `--browser` / `--no-browser` with [agent-browser](https://agent-browser.dev)

- auto-detects agent-browser when available

- config option: `capabilities.browser` in `.ralphy/config.yaml`



### v4.1.0

- TypeScript CLI: `npm install -g ralphy-cli`

- cross-platform binaries (macOS, Linux, Windows)

- no dependencies on jq/yq/bc for npm version



### v4.0.0

- single-task mode: `ralphy "task"` without PRD

- project config: `--init` creates `.ralphy/` with rules + auto-detection

- new: `--config`, `--add-rule`, `--no-commit`



### v3.3.0

- Factory Droid support (`--droid`)



### v3.2.0

- Qwen-Code support (`--qwen`)



### v3.1.0

- Cursor support (`--cursor`)

- better task verification



### v3.0.0

- parallel execution with worktrees

- branch-per-task + auto-PR

- YAML + GitHub Issues sources

- parallel groups



### v2.0.0

- OpenCode support

- retry logic

- `--max-iterations`, `--dry-run`



### v1.0.0

- initial release



## Contributing



See [CONTRIBUTING.md](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.md) - Claude Code instructions

- [.cursorrules](.cursorrules) - Cursor IDE rules



## Community



- [Discord](https://rasmic.link/discord)



## License



MIT