Skip to content
BSWEN
Blog

What is a Ralph Loop and How Do You Use It with Codex?

Cowrie
Cowrie
Dev @ Bswen

Purpose

This post explains what a Ralph Loop is and how to use it with Codex CLI to run AI coding agents autonomously for hours. The key point is setting up self-repeating execution patterns that chain tasks without manual intervention.

The Problem

I tried running Codex for long coding sessions. Every time, I hit the same wall: after 30 minutes, the agent stops and waits for my input.

Here’s what typically happens:

  1. I give Codex a complex task
  2. It works for a while, makes progress
  3. It hits a decision point and asks: “Should I proceed with X or Y?”
  4. I’m away from my desk, so everything stops

This breaks the flow. I wanted Codex to keep working while I grab coffee, attend meetings, or even sleep.

The Solution

A Ralph Loop solves this by setting up self-sustaining execution patterns. The agent creates its own next steps and triggers them automatically.

The name comes from the community. One Reddit user explained it simply: “Ralph loop or just give it a hard/time consuming task. Create a detailed plan with it, give it access to everything it needs, and tell it to start implementing your plan.”

Core Principles

There are four principles behind a successful Ralph Loop:

1. Comprehensive Planning Upfront

Before the loop starts, provide a complete plan. The agent shouldn’t need to ask for clarification.

plan.md
# URL Processing Task


## Goal
Process 100 URLs from urls.txt and extract metadata.


## Steps
1. Read each URL from urls.txt
2. Fetch the page content
3. Extract title, description, and keywords
4. Save results to output.json
5. Handle errors gracefully (log and continue)
6. Generate summary report when complete


## Error Handling
- If URL fails, log error and skip
- If rate limited, wait 60 seconds and retry
- If output.json exists, append to it

2. Context Pre-loading

Give the agent all context it needs before starting:

terminal
# Create context directory with all necessary files
mkdir -p context
cp urls.txt context/
cp config.json context/
cp templates/* context/


# Start Codex with context
codex --context ./context "Follow plan.md. Don't ask for clarification. Make reasonable assumptions and proceed."

3. Self-chaining Execution

The agent completes one task, then triggers the next task itself. This is the loop part.

4. Nested Loop Structure

Advanced users nest loops. One Reddit user explained: “Put a loop on agents on a key phrase. Then put a loop on that loop. Then loop that loop. Then queue up the overarching loop phrase 4 times.”

Here’s a visual representation:

Main Loop (4x queued)
  |
  +-- Phase 1 Loop
  |     |
  |     +-- Task A
  |     +-- Task B
  |     +-- Trigger Phase 2
  |
  +-- Phase 2 Loop
  |     |
  |     +-- Task C
  |     +-- Task D
  |     +-- Trigger Phase 3
  |
  +-- Phase 3 Loop
        |
        +-- Task E
        +-- Task F
        +-- Trigger Main Loop restart

How to Implement with Codex CLI

Here’s a step-by-step approach:

Step 1: Create a detailed plan file

implementation-plan.md
# Feature Implementation Plan


## Overview
Implement user authentication system with JWT tokens.


## Phase 1: Database Setup (Auto-proceed)
- Create users table migration
- Run migration
- Create User model
- Test database connection


## Phase 2: API Endpoints (Auto-proceed)
- POST /auth/register
- POST /auth/login
- POST /auth/refresh
- GET /auth/me


## Phase 3: Testing (Auto-proceed)
- Unit tests for each endpoint
- Integration tests for auth flow
- Fix any failing tests


## Phase 4: Documentation (Auto-proceed)
- API documentation
- README updates
- Usage examples


## Rules
- Don't ask for permission between phases
- Make reasonable assumptions
- Log all decisions made
- Continue until all phases complete

Step 2: Provide all necessary context

prepare-context.sh
# Copy all files Codex might need
cp -r src/ context/
cp -r tests/ context/
cp package.json context/
cp tsconfig.json context/
cp .env.example context/


# Create instruction file
cat > context/instructions.md << 'EOF'
# Execution Instructions


1. Read implementation-plan.md
2. Execute each phase sequentially
3. Don't stop between phases
4. If blocked, make a reasonable choice and note it
5. Run tests after each phase
6. Fix any issues found
7. Continue until all phases done
EOF

Step 3: Start the loop

start-loop.sh
codex --context ./context \
  --timeout 3600 \
  "Read instructions.md and implementation-plan.md. Execute all phases without stopping. Make reasonable assumptions when blocked. Log all decisions."

Step 4: Monitor progress (optional)

monitor.sh
# In a separate terminal, watch the log
tail -f codex.log


# Or check status periodically
codex status

Practical Example: URL Processing Loop

Here’s a complete example for processing URLs:

ralph-loop-skill.yaml
name: url-processor-loop
description: "Process URLs autonomously with loop trigger"
triggers:
  - phrase: "process the url queue"
    action: start_loop


steps:
  - name: "Load Queue"
    instruction: "Read urls.txt and load all URLs into memory"
    on_complete: "next"


  - name: "Process Batch"
    instruction: |
      Process 10 URLs:
      1. Fetch each URL
      2. Extract metadata
      3. Save to results.json
      4. Log any errors
    on_complete: "check_remaining"


  - name: "Check Remaining"
    instruction: |
      If URLs remain in queue:
        - Say "Processing next batch"
        - Trigger "process the url queue"
      Else:
        - Say "All URLs processed"
        - Generate final report
    on_complete: "end"


error_handling:
  - on_error: "Log error and continue with next URL"
  - on_rate_limit: "Wait 60 seconds, then retry"
  - on_fatal: "Save state and report issue"

Common Mistakes

I made these mistakes when setting up Ralph Loops:

1. Insufficient Planning

I gave vague instructions: “Implement the feature.” The agent kept asking questions. The loop broke.

The fix: provide detailed, explicit plans with numbered steps.

# BAD
"Implement authentication"


# GOOD
"Implement authentication with:
1. JWT tokens (RS256)
2. Refresh token rotation
3. Password hashing (bcrypt)
4. Rate limiting (5 attempts per minute)"

2. Missing Context

The agent couldn’t find files it needed. It stopped to ask for file paths.

The fix: pre-load all context files and use consistent naming.

3. No Failure Handling

When something went wrong, the agent stopped and asked what to do.

The fix: add explicit error handling rules.

## Error Handling Rules
- If file not found: Create it
- If test fails: Debug and fix
- If API returns error: Log and retry (max 3 times)
- If blocked for >5 min: Skip and note issue

4. Over-nesting

I created loops within loops within loops. Debugging was impossible.

The fix: limit to 2-3 levels of nesting. Keep each level simple.

# GOOD: 2 levels
Main Loop -> Phase Loop -> Tasks


# BAD: 5 levels
Main -> Phase -> Stage -> Step -> Sub-step -> Task

How It Works

The Ralph Loop works through self-triggering. When the agent completes a task, it outputs a trigger phrase. The system detects this phrase and starts the next iteration.

For example:

  1. Agent processes 10 URLs
  2. Agent outputs: “Batch complete. Processing next batch…”
  3. System detects “Processing next batch” as a trigger
  4. System re-invokes the agent with the same instructions
  5. Loop continues until completion condition met

This works because Codex maintains context across invocations when configured properly.

Summary

In this post, I explained the Ralph Loop technique for running AI coding agents autonomously. The key point is setting up self-repeating execution patterns through comprehensive planning, context pre-loading, and self-chaining triggers.

Key takeaways:

  1. Create detailed plans upfront with numbered steps
  2. Pre-load all context files before starting
  3. Add explicit error handling rules
  4. Use nested loops sparingly (2-3 levels max)
  5. Monitor progress through logs

Next steps:

  1. Try a simple Ralph Loop with a 100-line plan file
  2. Add error handling rules for common failure cases
  3. Gradually increase complexity as you learn the patterns
  4. Create reusable skill files for common loop patterns

The Ralph Loop transforms Codex from an interactive tool into an autonomous worker. With proper setup, you can give it a task in the morning and find it completed by evening.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: