I Used Ralph to Build a Full Feature – Here's How It Works

I explain Ralph, a prompting technique that runs AI agents in loops to build software features step by step. Instead of asking an AI to do a huge task at once, Ralph breaks it into smaller tasks and iterates over them, improving results over time.

I demonstrate how to apply Ralph with Claude AI and React Native (Expo), focusing on adding a prompt history feature to an AI tattoo app. I cover the bash loop script, task breakdown, and how the agent commits changes incrementally.

What's inside

• What Ralph Wigum is and its origin
• How Ralph improves AI agent prompting over time
• Using Ralph with a tattoo prompt history feature
• The bash loop script controlling iterations
• Managing a to-do list of features for the agent
• How the agent works on one feature at a time
• Committing changes and updating progress automatically
• Running the Ralph script with controlled iterations

What Ralph Wigum is and its origin

Ralph Wigum is a technique popularized by Joffrey Huntley that uses a bash loop to repeatedly prompt an AI agent like Claude until a task is complete. It was introduced in a blog post last year and is now gaining traction for building software incrementally with AI.

The idea is to keep prompting the agent in a loop, allowing it to tackle smaller tasks continuously rather than one big request. This approach enables shipping large features or even new software from scratch by iterating over manageable steps.

How Ralph improves AI agent prompting over time

Instead of a single large prompt, Ralph breaks down work into smaller features or tasks. The agent processes one feature per iteration, then updates a shared to-do list and progress log. This looped approach lets the AI improve results gradually and maintain context by reading previous commits and progress notes.

This method avoids overwhelming the AI with a huge context window and reduces token usage by limiting iterations. It also supports early exit when all tasks are complete, making it efficient for long-running autonomous coding.

Using Ralph with a tattoo prompt history feature

I apply Ralph to add a prompt history feature in my AI tattoo app. Users create tattoo prompts, but currently lose their prompt after submission. I want to save prompts using xosqlite for scalability and reusability.

The plan is to have a button in the input that opens a bottom sheet showing past prompts. Selecting one sets the input prompt again. I break this down into smaller tasks like creating a reactive package, implementing CRUD operations, adding UI components, and integrating React 19 features like Suspense and useActivity.

The bash loop script controlling iterations

The core of Ralph is a bash script that runs a for loop for a fixed number of iterations, passed as a parameter. This prevents infinite loops and excessive token usage.

The script checks for the iteration count argument and exits if missing. It calls Claude with flags to print the response and accept edits automatically. The script passes the to-do list and progress files to the agent each iteration, letting it pick the next feature to work on.

Managing a to-do list of features for the agent

The to-do list is a JSON file containing feature objects with category, description, and steps. The agent is only allowed to update a completion flag once a feature is done.

This structured list helps the agent prioritize and focus on one feature at a time. It also enables the agent to verify features and update the list progressively, ensuring clear tracking of what’s done and what remains.

How the agent works on one feature at a time

Each iteration, the agent picks the highest priority incomplete feature from the to-do list. It works exclusively on that feature, commits changes, and appends notes to a progress file.

This single-feature focus is important because each agent instance starts fresh with a limited context window. The agent uses git history and progress notes to understand recent work and decide the next task logically.

Committing changes and updating progress automatically

After completing a feature, the agent commits the changes to a dedicated branch. It also updates the to-do list JSON and appends progress notes to a TypeScript file.

This approach provides a clear audit trail and context for subsequent iterations. It also allows easy rollback by working on a separate branch and keeps the process automated without manual intervention.

Running the Ralph script with controlled iterations

To run the loop, you give the bash script executable permissions and call it with the number of iterations you want. For example, if you have 11 features, you run ./ralph.sh 12.

The script prints the iteration number and calls Claude each time. It exits early if the to-do list is marked complete. This controlled execution helps manage token usage and keeps the process predictable.

Resources

CourseReact Native course

Master React Native, TypeScript, and Git with practical projects and lifetime access.

Premium resourcePro membership

Get access to source code like the AI tattoo app and exclusive tutorials.