Ralph Scaffold
armarquez/ralph-scaffold
Scaffold para agentes IA autônomos executarem loops de coding estruturados
Ver no GitHubFramework agnóstico para implementar o Ralph loop — metodologia de agente IA autônomo para coding. Integra-se com Claude Code, OpenHands, Amp e qualquer CLI de agent, fornecendo orquestração de tarefas, execução de testes e circuit breakers automáticos.
Instalação
npx convez-ai armarquez/ralph-scaffold1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automatizar desenvolvimento de features com agentes IA
- Orquestrar múltiplas iterações de coding com circuit breakers
- Integrar agentes IA em pipelines CI/CD de projetos existentes
Veredito

Solução técnica madura para instrumentar agentes IA em loops de desenvolvimento. Reduz fricção ao integrar Claude Code e similares em projetos reais, com gestão de estado e proteções contra loops infinitos.
README
A tradução para o português deste README ainda está na fila.
ralph-scaffold
A tool-agnostic scaffold for the Ralph loop — the autonomous AI coding agent methodology. Drop it into any project and hand it to Claude Code, OpenHands, Amp, or any agent CLI.
What is this?
The Ralph loop is a structured approach to autonomous coding: the agent reads a task list,
implements one task at a time, runs tests, commits, and repeats. ralph-scaffold gives you:
task_runner.py— reads/writesprd.jsonstate: next task, mark complete, mark blockedralph.py— loop runner: calls your agent CLI, checks progress, enforces circuit breakerspre-commithook — blocks commits when tests failPROMPT.md/AGENTS.md— agent-readable context templatesjust onboard <path>— one command to scaffold a project and get a setup checklist
Prerequisites
mise— manages Python, uv, and just (install once:curl https://mise.run | sh)just— installed automatically viamise install- Python 3.12+ — installed automatically via
mise install uv— installed automatically viamise install- A git repo to install into
- An agent CLI (Claude Code, OpenHands, Amp, etc.)
Quickstart
Step 1 — Clone and install tools:
git clone https://github.com/armarquez/ralph-scaffold
cd ralph-scaffold
mise install # installs Python 3.12, uv, and just
just install # syncs dev deps and wires the pre-commit hook
Step 2 — Onboard your project:
just onboard /path/to/your-project
This copies the scaffold files and prints a checklist of what to fill in next.
Run just setup /path/to/your-project any time to reprint the checklist.
Step 3 — Fill in the templates and run:
Follow the checklist from Step 2, then:
cd /path/to/your-project
just status # verify task list loaded correctly
just ralph # dry-run to preview what the loop would call
just loop # start the loop (calls your agent until all tasks pass)
File Reference
| Path | Purpose |
|---|---|
install.sh | Entry point: copies scaffold into target project |
scaffold/scripts/ralph.py | Loop runner — calls agent, checks exit gate, circuit breaker |
scaffold/scripts/task_runner.py | prd.json state machine |
scaffold/hooks/pre-commit | Git hook: runs just check or .ralphrc.json test_cmd |
scaffold/.ralph/PROMPT.md | Agent instructions template |
scaffold/.ralph/AGENTS.md | Build/test/lint commands template |
scaffold/prd.json.example | Annotated prd.json template |
scaffold/justfile.example | justfile template with EDIT THIS markers |
scaffold/.mise.toml.example | .mise.toml template with tool pins |
prd.json | This repo's own task list (self-hosting example) |
.ralph/ | This repo's own filled-in agent context |
How the Loop Works
flowchart TD
A[ralph.py starts] --> B[read .ralphrc.json]
B --> C[task_runner.py next]
C --> D{done?}
D -- yes --> E[exit 0]
D -- no --> F[shell out to agent_cmd]
F --> G[check git diff]
G --> H[append progress.txt]
H --> I{circuit breaker?}
I -- tripped --> J[exit 2]
I -- ok --> K{max_loops?}
K -- hit --> J
K -- ok --> C
- Circuit breaker opens after N loops with no file changes (
no_progress_threshold) or N loops with the same error output (same_error_threshold). - Exit gate is checked each loop via
task_runner.py next. When all non-optional tasks havepasses: true, it returns{"done": true}and the loop exits cleanly.
Contributing
- Fork the repo
- Run
mise installto get Python, uv, and just - Run
just installto install dev deps and wire the pre-commit hook - Work through
TASKS.mdtop-to-bottom - Run
just checkbefore every commit - Open a PR against
main