Repolode
Submit
ClaytonFarr

ClaytonFarr/ralph-playbook

A guide to running autonomous AI coding loops with Geoff Huntley's Ralph methodology, covering planning, building, specs and prompt templates.

View on GitHubWebsite
Stars
1,037
Forks
266
Open issues
3
Last commit
8 months ago

What is it?

The Ralph Playbook is a practical guide to Ralph, a method for running AI coding agents in an autonomous loop. Each iteration starts with a fresh context, reads a prompt file and a shared implementation plan on disk, completes one task, commits, and exits, so the agent keeps making progress without manual orchestration.

The guide breaks the workflow into three phases: defining requirements as topic-specific spec files, a planning loop that performs gap analysis between specs and code, and a building loop that implements tasks against tests and other backpressure. It includes ready-to-adapt PROMPT_plan and PROMPT_build templates, an AGENTS.md convention for build and test commands, a sample loop.sh script, and guidance on sandboxing an agent that runs with permissions skipped.

The repository also outlines proposed extensions, such as deriving test requirements from acceptance criteria, LLM-as-judge reviews for subjective quality, and reverse-engineering existing codebases into specs. It is published as a formatted web guide as well as Markdown.

Key features

  • 01Defines a three-phase workflow from requirements to planning to building
  • 02Provides PLANNING and BUILDING prompt templates for Claude-style coding agents
  • 03Includes a sample loop.sh that supports mode selection and max-iteration limits
  • 04Describes AGENTS.md and implementation plan conventions for shared state between iterations
  • 05Covers sandboxing guidance for running agents with permissions skipped

Use cases

  • Setting up an autonomous coding loop that implements a project from written specs
  • Structuring prompts and planning files for an AI agent working across many small tasks
  • Reviewing safe execution practices before running coding agents with broad permissions

Quick start

  1. 1

    Read the Ralph Playbook guide in the README

  2. 2

    Set up the basic loop script used for autonomous runs

    while :; do cat PROMPT.md | claude ; done

Things to know

  • The repository is a methodology guide, not a installable software package.
  • The example loop runs Claude with --dangerously-skip-permissions, so it needs an isolated sandbox for safety.
  • Results depend on careful prompt, spec and backpressure tuning and may be nondeterministic.

Topics

#ai-agents#coding-agent#prompt-engineering#llm#automation#claude#developer-workflow

FAQ

What is ralph-playbook?
A guide to running autonomous AI coding loops with Geoff Huntley's Ralph methodology, covering planning, building, specs and prompt templates. The Ralph Playbook is a practical guide to Ralph, a method for running AI coding agents in an autonomous loop. Each iteration starts with a fresh context, reads a prompt file and a shared implementation plan on disk, completes one task, commits, and exits, so the agent keeps making progress without manual orchestration.
Is ralph-playbook free to use? What license does it have?
ralph-playbook is open source under the MIT license. Check the license terms before using it in commercial products.
Is ralph-playbook still maintained?
No commits for 6+ months. The last commit to ralph-playbook was on Mar 6, 2026.
What can I use ralph-playbook for?
Setting up an autonomous coding loop that implements a project from written specs Structuring prompts and planning files for an AI agent working across many small tasks Reviewing safe execution practices before running coding agents with broad permissions
How do I install ralph-playbook?
Read the Ralph Playbook guide in the README Set up the basic loop script used for autonomous runs: while :; do cat PROMPT.md | claude ; done
Where can I get ralph-playbook?
The source code and installation instructions are on GitHub: https://github.com/ClaytonFarr/ralph-playbook

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects