FAQ

Frequently Asked Questions

General

What is ralph?

ralph is a CLI tool that runs AI coding agents in iterative loops. It resets the context window between iterations while preserving state through your codebase, allowing AI agents to work on complex tasks for hours instead of minutes.

Why is it called “Ralph Wiggum”?

The technique was coined by Geoffrey Huntley, who observed that a simple bash loop running an AI agent could accomplish remarkable things through persistence. He named it after Ralph Wiggum from The Simpsons—capturing the philosophy of being “deterministically stubborn in an undeterministic world.”

How is this different from just using Claude Code / OpenCode directly?

When you use an AI tool directly, context accumulates. As the context window fills, model performance degrades. ralph solves this by:

1. Running your AI tool with a prompt
2. Letting it work until it exits
3. Resetting context (new session)
4. Running the same prompt again
5. Repeating until done

The AI reads your updated codebase each iteration, so progress persists even though context resets.

Is this just running the same thing over and over?

No! The prompt stays the same, but the codebase changes. Each iteration:

• The model reads updated files
• Sees test results from previous work
• Checks progress markers
• Continues from where the last iteration left off

It’s like having a fresh developer join the project each morning—they read the code and continue the work.

---

Technical

What AI tools does ralph support?

ralph supports:

• Claude Code — Anthropic’s official CLI (recommended)
• OpenCode — Open-source alternative with multi-provider support
• Gemini CLI — Under development

Does ralph require an API key?

ralph itself doesn’t need an API key—it orchestrates other tools. Your AI tool (Claude Code, OpenCode, etc.) needs appropriate API credentials.

How does ralph know when to stop?

ralph stops when:

1. Completion marker — The AI outputs <promise>COMPLETE</promise>
2. Max iterations — Reached the maxIterations limit
3. Error — The AI process exits with non-zero code
4. User interrupt — You press Ctrl+C

Configure the iteration limit in .ralph/config.toml:

maxIterations = 20

How does state persist between iterations?

State lives in your codebase:

• Git commits — History of changes
• Files — Updated code, progress markers
• Test results — What passes/fails
• progress.txt — Explicit status tracking

The AI reads these each iteration to understand current state.

Won’t the AI undo its own work?

Rarely. The model reads what exists and continues from there. Good prompts include:

Check progress.txt for completed work.
Don't repeat work that's already done.

If you’re seeing this issue, make state more explicit.

---

Cost and Performance

How much does ralph cost?

ralph itself is free. You pay for AI API usage (Anthropic, OpenAI, etc.).

Typical costs vary by task:

• Small refactor: $5-20
• Test coverage project: $20-50
• Large migration: $50-200

How can I reduce costs?

1. Use smaller models — Sonnet over Opus for mechanical work
2. Set iteration limits — Don’t let it run forever
3. Focused prompts — Smaller prompts = fewer tokens per iteration
4. File references — “See GUIDELINES.md” instead of embedding content
5. Local models — OpenCode with Ollama (free but slower)

How long does a typical ralph run take?

Depends on the task:

• Quick refactor: 10-30 minutes, 5-10 iterations
• Test coverage: 30-60 minutes, 15-30 iterations
• Large migration: 2-4 hours, 30-50 iterations

Each iteration typically takes 2-10 minutes depending on model and task complexity.

---

Troubleshooting

ralph loops forever / never exits

Check your prompt includes a clear completion instruction:

## Completion
When all tests pass, output:
<promise>COMPLETE</promise>

Always set maxIterations as a safety net.

The AI keeps making the same changes

Your prompt might not be clear about checking existing work:

## Before Starting
1. Check progress.txt for completed items
2. Run `git log --oneline -5` to see recent changes
3. Only work on items NOT already done

Tests fail after ralph runs

The AI might have introduced bugs. Options:

1. Add test requirements to your prompt
2. Include verification commands
3. Review changes before merging

## After Each Change
Run `npm test` to verify tests still pass.

ralph uses too many tokens

Keep prompts concise. Instead of:

[500 lines of detailed instructions]

Use:

See TASK.md for detailed instructions.
Check progress.txt for status.

The AI forgets instructions

With context resets, the AI only knows what it reads. Ensure important instructions are in:

• Your prompt file
• Code comments
• A GUIDELINES.md file referenced in the prompt

---

Best Practices

What makes a good ralph prompt?

1. Clear goal — What’s the end state?
2. Verification — How does the AI check its work?
3. Progress tracking — How does state persist?
4. Exit criteria — When should it output the completion marker?

Example structure:

# Task
[What to do]

# Guidelines
[How to do it]

# Verification
[Commands to check work]

# Progress
[How to track and check progress]

# Completion
[When to output <promise>COMPLETE</promise>]

Should I use ralph for everything?

No. ralph excels at:

• Repetitive, systematic tasks
• Large-scale refactoring
• Test coverage
• Documentation
• Migrations

Don’t use ralph for:

• Quick one-off questions
• Exploratory work
• Highly interactive tasks
• Tasks that need human judgment each step

How many iterations should I allow?

Start conservative (20-30) and increase if needed. Watch the first run to understand the pattern, then adjust.

For reference:

• Simple task: 10-20 iterations
• Medium task: 20-40 iterations
• Complex task: 40-100 iterations

Still have questions?

Check the GitHub Issues or start a discussion. The community is friendly!