Making the 'ralph loop' Easy to Try: Let AI Write Code While You Sleep

Recently, I was inspired by the autonomous coding agent loop called Ralph, which Ryan Carson introduced on X, and I decided to create something similar myself.

https://x.com/ryancarson/status/2008548371712135632

The idea is to provide an AI agent with a task list, and then let it automatically select, implement, test, and commit tasks while rotating through a loop as it updates progress.
So, I created something simple that can be used with any CLI-based AI agent.
It seems it was originally implemented as a plugin for Claude Code.

https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum#prompt-writing-best-practices

You can easily try out what Ralph is like in the following repository.

https://github.com/syuya2036/ralph-loop

Sometimes it might not work well because it's not in its best condition, so please try adjusting the prompts and give it another shot.

What is Ralph?

Ralph is an autonomous coding loop implemented as a bash script.

1. Pass a task list (prd.json) and context prompts to the AI agent.
2. The AI selects one story, implements it, runs tests, commits, and updates progress.
3. Repeat until all stories are completed.

In step 2, the AI agent writes its progress and what it learned into progress.txt as needed, and then refers back to it in the next loop.
Additionally, it creates a new branch for each task.

Setup

1. Clone the repository

   git clone https://github.com/syuya2036/ralph-loop.git
   cd ralph-loop
   

2. Create a task list: Write user stories in prd.json

   • A sample task list for implementing a simple wc command in Rust is included.

Sample prd.json

{
	"branchName": "feat/mini-wc-cli",
	"userStories": [
		{
			"id": "US-001",
			"title": "Initialize Rust project and Basic Setup",
			"acceptanceCriteria": [
				"Initialize a new binary project with cargo init if Cargo.toml doesn't exist",
				"Create a main.rs that prints 'Hello, mini-wc!'",
				"cargo run executes successfully",
				"cargo check passes"
			],
			"priority": 1,
			"passes": false,
			"notes": ""
		},
		{
			"id": "US-002",
			"title": "Add Argument Parsing",
			"acceptanceCriteria": [
				"Add clap dependency to Cargo.toml",
				"Update main.rs to accept a file path as an argument",
				"If no argument is provided, print usage help",
				"cargo check passes"
			],
			"priority": 2,
			"passes": false,
			"notes": ""
		},
		{
			"id": "US-003",
			"title": "Implement Line Counting",
			"acceptanceCriteria": [
				"Read the file specified by the argument",
				"Count the number of lines in the file",
				"Print the line count to stdout (e.g., 'Lines: 10')",
				"Handle file not found errors gracefully",
				"cargo test passes (add a unit test for counting logic if possible)"
			],
			"priority": 3,
			"passes": false,
			"notes": ""
		},
		{
			"id": "US-004",
			"title": "Implement Word and Byte Counting",
			"acceptanceCriteria": [
				"Extend logic to count words and bytes as well",
				"Print all three stats: Lines, Words, Bytes",
				"Ensure format is readable",
				"cargo test passes"
			],
			"priority": 4,
			"passes": false,
			"notes": ""
		}
	]
}

3. Grant execution permissions

   chmod +x ./ralph-loop/ralph.sh
   

Usage

Run the script and pass the AI agent's CLI command as the first argument. The loop will run until the tasks in prd.json are completed, but for safety, you can specify the maximum number of iterations as the second argument.

./ralph-loop/ralph.sh "<YOUR_AGENT_COMMAND>" [MAX_ITERATIONS]

Examples

Codex CLI

./ralph-loop/ralph.sh "codex exec --full-auto" 20

Gemini CLI

./ralph-loop/ralph.sh "gemini --yolo" 20

Qwen Code

After enabling YOLO mode in the settings:

./ralph-loop/ralph.sh "qwen" 20

Conclusion

I've made it possible to easily use the Ralph loop with any AI agent. If you're interested, please give it a try!
→ https://github.com/syuya2036/ralph-loop