curl -fsSL https://raw.githubusercontent.com/Mizerness/Ralphy/main/install.sh | bash

What it does

You add a project (a git repo) and drop tasks into the backlog like orders on a pass. When you "open the kitchen", Ralphy runs each task autonomously:

1. 📋 Plan — runs Claude Code in plan mode (read-only): deep web research, reads your code, and writes a detailed plan.md.
2. 🔧 Execute — works the plan one checked-off step at a time, full-autonomy, until the task is done and its tests pass.
3. ⬆️ Ship — commits and pushes to a dedicated ralphy/task-* branch. You review the PR.

It runs unattended overnight: it keeps the Mac awake, survives Wi-Fi blips, backs off when it hits Claude usage limits, throttles when the machine is busy, skips tasks that need you, and only ever wakes you (literally, out loud) as a last resort.

Features

• Plan-first loop — separate read-only planning pass (Claude Code plan mode) feeds an execution loop. The plan is visible in the UI and committed as plan.md.
• Full autonomy, guarded — runs with --dangerously-skip-permissions behind a PreToolUse guardrail that blocks the scary stuff: pushing to main, force-push, terraform apply, rm -rf /, prod DB clients, DROP/TRUNCATE, and more.
• Browser automation — Playwright MCP wired in, so a task can log in, fetch a key, or scrape a page on its own.
• Never spins — detects "you've hit your session limit · resets 10am" and sleeps until the reset instead of hammering the API.
• Circuit breaker — stops a task that's stuck (no progress / same recommendation repeated) and parks it as needs input; state survives restarts.
• Global scheduler — runs up to max_concurrent task loops at once (default 5), spread least-loaded across your projects, FIFO within each. Tune the concurrency live from the UI.
• Worktree isolation — every running task works in its own git worktree, so several tasks of the same repo can cook concurrently without stomping each other.
• Resumable tasks — a stopped or interrupted task picks up where it left off: the Claude session id is persisted, so loop count, tokens, and the conversation carry across restarts.
• Attach a local session — start a task from an existing local Claude Code session (~/.claude/projects/...) to hand off a conversation you began by hand and let Ralphy finish it.
• Resource-aware — auto-throttles when CPU/RAM is saturated (never kills work in flight).
• Safe by default — work only ever lands on ralphy/* branches; never your main branch.
• Token budget — per-task cap so a runaway task can't burn your whole night.
• Live dashboard — kanban board (Backlog / Cooking / Served), live streamed output, per-task plan modal, and machine/power/network indicators.

Requirements

• macOS (uses caffeinate, pmset, say — core loop works elsewhere, those niceties don't)
• Python 3.11+
• git
• Claude Code CLI — claude on your PATH, logged in
• Node.js / npx (optional) — only for the Playwright browser tools

Install

One-liner (installs via pipx if present, else pip --user):

curl -fsSL https://raw.githubusercontent.com/Mizerness/Ralphy/main/install.sh | bash

Or from a clone:

git clone https://github.com/Mizerness/Ralphy.git
cd Ralphy
./install.sh

Or straight from pip / pipx:

pipx install git+https://github.com/Mizerness/Ralphy.git

Usage

ralphy            # starts the server and opens the dashboard in your browser

Then:

1. + New project → point it at a local git repo.
2. + New order → add tasks (a title + a clear description).
3. ▶ Open kitchen → Ralphy's scheduler starts cooking the backlog (FIFO, several tasks at once across your projects).

Leave it running overnight. In the morning, review the ralphy/task-* branches it pushed.

ralphy --port 8080      # custom port
ralphy --no-browser     # don't auto-open the browser

How it works

task ── PLAN (claude --permission-mode plan, read-only) ── plan.md ──┐
                                                                     ▼
        EXEC loop (claude --dangerously-skip-permissions) ── step by step ── tests ──┐
                          │  guardrail hook screens every Bash command               │
                          │  circuit breaker / token cap / session-limit backoff     │
                          ▼                                                           ▼
                  commit + push to ralphy/task-*                                  ✅ done

State lives in ~/.ralphy/ralphy.db (SQLite). Generated Claude Code configs (claude-settings.json with the guardrail hook, playwright-mcp.json) live in ~/.ralphy/.

Safety

Ralphy runs Claude with permissions bypassed so it can work unattended — the guardrail hook (src/ralphy/guardrail.py) is the net that makes that safe. It blocks destructive and production-touching commands and lets everything else through. Work is always committed to a ralphy/* branch and pushed there — never to main/master.

Still: run Ralphy on repos and a machine where that trade-off is acceptable, and review the branches it produces before merging.

Configuration

Settings live in the settings table of ~/.ralphy/ralphy.db (sensible defaults are seeded):

Development

python3.12 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest        # 33 tests
.venv/bin/python -m uvicorn ralphy.app:app --reload --port 7842

Credits

• ralph-claude-code by Frank Bria — Ralphy is a Python port + reimagining of it; the loop, circuit breaker, status parsing, and dual-condition exit are based on its design.
• Geoffrey Huntley — inventor of the "ralph" technique (the while :; do cat PROMPT.md | claude-code; done loop) Ralphy is named after.
• Claude Code — the CLI Ralphy drives.

License

MIT