Ralph

A simple autonomous engineering loop for Claude Code. Named after Ralph Wiggum because dumber methods win.

Read the blog post

Ralph treats each Claude session as one engineer in a relay team. Each picks up where the last left off, completes ONE task, commits, and exits. The bash loop spawns the next engineer.

Complex agent orchestrators encode assumptions about how work should flow. Ralph encodes almost nothing. It just runs Claude in a loop and lets the model figure out what to do next.

This works because:

• Modern models (Opus 4.7, GPT 5.2) are good enough to handle reasonable tasks without elaborate guardrails
• Files and git commits carry state between sessions, not conversation history
• Failures are predictable because the prompt never changes
• The model can break large tasks into smaller ones when needed

Read more: Ralph Loops: Your Agent Orchestrator Is Too Clever

Ralph lives on Airskills. One install drops the skill instructions and the bash runner into ~/.claude/skills/ralph/:

npx airskills add chrismdp/ralph

Then in any project with a docs/tickets/ (or docs/changes/) directory:

bash ~/.claude/skills/ralph/ralph.sh        # up to 10 iterations (default)
bash ~/.claude/skills/ralph/ralph.sh 100    # up to 100 iterations

A ticket is just a markdown file with frontmatter:

---
status: todo
title: Add login form to homepage
created: 2026-05-10
---

# What

A user lands on the homepage and sees a login form with email + password fields.

# Acceptance

- Form submits to `/api/login`
- Invalid credentials show an inline error
- Successful login redirects to `/dashboard`

Ralph picks the next todo, flips it to doing, does the work, commits, flips to done, exits. The loop spawns the next engineer.

Skill page: https://airskills.ai/chrismdp/ralph

For longer sessions, run a planning terminal alongside the build loop:

Left: an interactive Claude session for planning. Top right: Ralph loop building autonomously. Bottom right: dev server for verification.

Terminal 1 (Ralph Loop):

bash ~/.claude/skills/ralph/ralph.sh 100

Terminal 2 (Planning):

claude
# Type /ralph and ask it to write the tickets you want. The skill knows the ticket format
# and the problem-first style, so it'll drop new files into docs/tickets/ in the right
# shape. The loop picks them up on the next iteration.

The skill installs into your own ~/.claude/skills/ralph/ — edit anything you like. Tighten the prompt, add steps, swap commands. To save your changes back to Airskills (so they sync across machines):

cd ~/.claude/skills
airskills push

Ralph burns through tokens. Running this setup continuously requires a Max20 plan or higher. The value is worth it if you're building something real.

Context is investment. When Ralph blocks on a decision, treat it as a context failure. Add more documentation so future sessions can decide autonomously.

Use status: blocked for human-only work. Some things can't be automated (microphone input, complex gestures, product calls). Flip the ticket to blocked with a ## Notes section explaining why, and handle it in an interactive session.

Symlink your notes. If you have a second brain or documentation vault, symlink relevant files into the repo so Ralph can look things up.

• Your Agent Orchestrator Is Too Clever — why dumb methods win
• Running Ralph in Production — what 2 months of real use taught me

• /ralph skill on Airskills — the canonical install
• ralph-kit — Josh Chisholm's ready-to-use template
• Gas Town — Steve Yegge's more elaborate (too elaborate?) system

MIT