OpenRalph is an autonomous AI agent loop that runs OpenCode repeatedly until all PRD items are complete. Each iteration is a fresh OpenCode instance with clean context. Memory persists via git history, progress.txt, and prd.json.

Based on Geoffrey Huntley's Ralph pattern.

Read my in-depth article on how I use Ralph

• OpenCode CLI installed and authenticated
• jq installed (brew install jq on macOS)
• A git repository for your project

Copy the ralph files into your project:

# From your project root
mkdir -p scripts/ralph
cp /path/to/ralph/ralph.sh scripts/ralph/
cp /path/to/ralph/prompt.md scripts/ralph/
chmod +x scripts/ralph/ralph.sh

Copy the agents to your OpenCode config for use across all projects:

cp -r .opencode/agent/* ~/.config/opencode/agent/

The project includes an opencode.json config file that allows all permissions (equivalent to --dangerously-allow-all). OpenCode will automatically use this configuration when running in the project directory.

For context management, OpenCode handles this automatically. You can disable automatic context compaction if needed by setting OPENCODE_DISABLE_AUTOCOMPACT=true in your environment.

Use the PRD agent to generate a detailed requirements document:

@prd create a PRD for [your feature description]

Answer the clarifying questions. The agent saves output to tasks/prd-[feature-name].md.

Use the OpenRalph converter agent to convert the markdown PRD to JSON:

@ralph-converter convert tasks/prd-[feature-name].md to prd.json

This creates prd.json with user stories structured for autonomous execution.

./scripts/ralph/ralph.sh [max_iterations]

Default is 10 iterations.

OpenRalph will:

1. Create a feature branch (from PRD branchName)
2. Pick the highest priority story where passes: false
3. Implement that single story
4. Run quality checks (typecheck, tests)
5. Commit if checks pass
6. Update prd.json to mark story as passes: true
7. Append learnings to progress.txt
8. Repeat until all stories pass or max iterations reached

View Interactive Flowchart - Click through to see each step with animations.

The flowchart/ directory contains the source code. To run locally:

cd flowchart
npm install
npm run dev

Each iteration spawns a new OpenCode instance with clean context. The only memory between iterations is:

• Git history (commits from previous iterations)
• progress.txt (learnings and context)
• prd.json (which stories are done)

Each PRD item should be small enough to complete in one context window. If a task is too big, the LLM runs out of context before finishing and produces poor code.

Right-sized stories:

• Add a database column and migration
• Add a UI component to an existing page
• Update a server action with new logic
• Add a filter dropdown to a list

Too big (split these):

• "Build the entire dashboard"
• "Add authentication"
• "Refactor the API"

After each iteration, OpenRalph updates the relevant AGENTS.md files with learnings. This is key because OpenCode automatically reads these files, so future iterations (and future human developers) benefit from discovered patterns, gotchas, and conventions.

Examples of what to add to AGENTS.md:

• Patterns discovered ("this codebase uses X for Y")
• Gotchas ("do not forget to update Z when changing W")
• Useful context ("the settings panel is in component X")

OpenRalph only works if there are feedback loops:

• Typecheck catches type errors
• Tests verify behavior
• CI must stay green (broken code compounds across iterations)

Frontend stories must include "Verify in browser using dev-browser skill" in acceptance criteria. OpenRalph will use browser tools to navigate to the page, interact with the UI, and confirm changes work.

When all stories have passes: true, OpenRalph outputs <promise>COMPLETE</promise> and the loop exits.

Check current state:

# See which stories are done
cat prd.json | jq '.userStories[] | {id, title, passes}'

# See learnings from previous iterations
cat progress.txt

# Check git history
git log --oneline -10

Edit prompt.md to customize OpenRalph's behavior for your project:

• Add project-specific quality check commands
• Include codebase conventions
• Add common gotchas for your stack

OpenRalph automatically archives previous runs when you start a new feature (different branchName). Archives are saved to archive/YYYY-MM-DD-feature-name/.

• Geoffrey Huntley's Ralph article
• OpenCode documentation