Ralphy

You can install the Ralphy CLI globally using npm. This version is cross-platform (macOS, Linux, Windows) and does not require external dependencies like jq, yq, or bc.

npm install -g ralphy-cli

Install the ralphy-cli globally using npm to use Ralphy from anywhere in your terminal.

Requirements:

• Node.js 18+ or Bun
• An AI CLI installed (e.g., Claude Code, OpenCode, Cursor, etc.)

npm install -g ralphy-cli

Ralphy can use agent-browser to perform UI testing and interactions. This is useful for verifying deployments or testing user flows.

Usage:

• --browser: Force enable browser automation.
• --no-browser: Force disable browser automation.
• Default: Auto-detect.

Available Browser Commands for the AI:

• agent-browser open <url>
• agent-browser snapshot (returns element refs like @e1)
• agent-browser click @e1
• agent-browser type @e1 "text"
• agent-browser screenshot <file>

ralphy "test the login flow" --browser

To pass arguments directly to the underlying engine CLI without Ralphy interpreting them, use the -- separator. Everything after -- is passed verbatim to the engine.

# 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

# Pass custom arguments to any engine
ralphy --cursor "fix bug" -- --custom-arg value

Ralphy supports two primary execution modes:

1. Single task: Pass a direct instruction string to perform a specific action.
2. Task list: Work through a structured list of tasks defined in a PRD (Product Requirements Document) file. By default, it looks for PRD.md in the current directory.

Examples:

• Single task: ralphy "add dark mode"
• Task list (default file): ralphy
• Task list (custom file): ralphy --prd tasks.md

You can install Ralphy using npm (recommended) or by cloning the repository.

Using npm:

npm install -g ralphy-cli

Using Clone:

git clone https://github.com/michaelshimeles/ralphy.git
cd ralphy && chmod +x ralphy.sh

Note: If using the bash script version, substitute ralphy with ./ralphy.sh in all commands.

To ensure better code quality and more reliable execution, break large tasks into 'micro-tasks'. Instead of a single large task, provide a sequence of granular, actionable steps.

Example of a good micro-task breakdown:

- [ ] Create User model with email and password fields
- [ ] Add password hashing utility function
- [ ] Create signup API endpoint
- [ ] Create login API endpoint
- [ ] Add session/token generation
- [ ] Create logout endpoint

For large repositories with massive dependency directories (like node_modules), use --sandbox mode. This is faster and more efficient than standard git worktrees.

How it works:

• Symlinks: Read-only dependencies (e.g., node_modules, .git, .venv) are symlinked.
• Copies: Source files that agents modify (e.g., src/, app/) are copied.

When to use:

• Use --sandbox for large monorepos to avoid duplicating gigabytes of data.
• Use the default (git worktrees) when you need full git history access or need to run complex git commands within the sandbox.

ralphy --parallel --sandbox

Ralphy can execute multiple agents simultaneously.

Parallel Execution:

• ralphy --parallel: Runs with 3 agents by default.
• ralphy --parallel --max-parallel 5: Runs with 5 agents.

Sandbox Mode: For large repositories, use --sandbox to speed up execution. Instead of using git worktrees, Ralphy will use symlinks for read-only dependencies (like node_modules) and copies for source files. This avoids duplicating gigabytes of data.

ralphy --parallel --sandbox

Workflow Control:

• --no-merge: Keeps branches without merging or creating PRs.
• --create-pr: Keeps branches and creates PRs.
• --branch-per-task: Creates a unique branch for every task.