Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (morty-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Ralphy

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

Install

npm install -g ralphy-cli

Quick Start

# Single task
ralphy "add login button"

# Work through a task list
ralphy --prd PRD.md

Two Modes

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

Project Config

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"

AI Engines

ralphy              # Claude Code (default)
ralphy --opencode   # OpenCode
ralphy --cursor     # Cursor
ralphy --codex      # Codex
ralphy --qwen       # Qwen-Code
ralphy --droid      # Factory Droid

Model Override

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"

Task Sources

Markdown file (default):

ralphy --prd PRD.md

Markdown folder (for large projects):

ralphy --prd ./prd/

Reads all .md files in the folder and aggregates tasks.

YAML:

ralphy --yaml tasks.yaml

GitHub Issues:

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

Parallel Execution

ralphy --parallel                  # 3 agents default
ralphy --parallel --max-parallel 5 # 5 agents

Each agent gets isolated worktree + branch. Without --create-pr: auto-merges back with AI conflict resolution. With --create-pr: keeps branches, creates PRs. With --no-merge: keeps branches without merging.

Branch Workflow

ralphy --branch-per-task                # branch per task
ralphy --branch-per-task --create-pr    # + create PRs
ralphy --branch-per-task --draft-pr     # + draft PRs

Browser Automation

Ralphy supports browser automation via agent-browser for testing web UIs.

ralphy "add login form" --browser    # enable browser automation
ralphy "fix checkout" --no-browser   # disable browser automation

When enabled (and agent-browser is installed), the AI can:

Open URLs and navigate pages
Click elements and fill forms
Take screenshots for verification
Test web UI changes after implementation

Options

Flag	What it does
`--prd PATH`	task file or folder (auto-detected, default: PRD.md)
`--yaml FILE`	YAML task file
`--github REPO`	use GitHub issues
`--github-label TAG`	filter issues by label
`--model NAME`	override model for any engine
`--sonnet`	shortcut for `--claude --model sonnet`
`--parallel`	run parallel
`--max-parallel N`	max agents (default: 3)
`--no-merge`	skip auto-merge in parallel mode
`--branch-per-task`	branch per task
`--base-branch BRANCH`	base branch for PRs
`--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
`--browser`	enable browser automation
`--no-browser`	disable browser automation
`--max-iterations N`	stop after N tasks
`--max-retries N`	retries per task (default: 3)
`--retry-delay N`	delay between retries in seconds (default: 5)
`--dry-run`	preview only
`-v, --verbose`	debug output
`--init`	setup .ralphy/ config
`--config`	show config
`--add-rule "rule"`	add rule to config

Requirements

Node.js 18+ or Bun
AI CLI: Claude Code, OpenCode, Cursor, Codex, Qwen-Code, or Factory Droid
gh (optional, for GitHub issues / --create-pr)

License

MIT

morty-cli