how-to-guide

How to Debug Ralph When Iterations Stall or Stories Are Incomplete

April 13, 2026 snarktank/ralph ↗

When Ralph stalls or leaves user stories incomplete, inspect the captured OUTPUT for tool crashes, verify the <promise>COMPLETE</promise> sentinel appears in logs, confirm progress.txt records new iterations, and ensure prd.json updates story status to passes: true.

Ralph is a self-contained autonomous AI agent loop developed by snarktank that repeatedly invokes Amp or Claude Code until every user story in your PRD is marked complete. The orchestration logic lives entirely in ralph.sh, which manages branch archiving, progress logging

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:

curl -s "https://instagit.com/install.md"

Add to your MCP client configuration:

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}

Ask your agent:

"Use Instagit MCP to understand how snarktank/ralph works."

Works with

Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →