Exit Conditions

Exit Conditions

Exit conditions tell ralph when the job is done. Without them, ralph would loop forever.

How ralph Exits

ralph checks for exit conditions after each iteration:

Exit Reasons

ralph exits for one of these reasons:

1. Complete

The AI outputs the completion marker <promise>COMPLETE</promise>. This is the success case—the task is done.

2. Max Iterations

Reached the maxIterations limit from config. This is a safety net to prevent runaway loops.

3. Error

The AI process exited with a non-zero code.

4. User Abort

User interrupted with Ctrl+C.

The Completion Marker

ralph detects task completion when the AI outputs:

<promise>COMPLETE</promise>

Include this in your prompt instructions:

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

Why This Marker?

The marker gives the AI explicit control over when to signal completion. This is more reliable than trying to parse test output or exit codes, which vary between tools and projects.

Max Iterations

Always configure a reasonable maxIterations in .ralph/config.toml:

maxIterations = 20

This prevents:

• Runaway API costs
• Infinite loops when the AI can’t complete the task
• Wasted time on impossible tasks

Always Set a Limit

Even well-designed prompts can get stuck. Always set maxIterations as a safety net.

Choosing a Limit

Task Type	Suggested Limit
Simple fixes	5-10
Test coverage	15-30
Large refactors	30-50
Complex migrations	50-100

Start conservative and increase if needed.

Designing for Completion

Be Explicit

Tell the AI exactly when to signal completion:

## Completion
When `npm test` passes AND coverage is above 80%, output:
<promise>COMPLETE</promise>

Make Progress Visible

Help the AI track what’s done:

## Progress
1. Check progress.txt for completed items
2. Update progress.txt after each task
3. When all items are done, output the completion marker

Include Verification Steps

Tell the AI how to verify success:

## Verification
Before signaling completion:
1. Run `npm test` - all tests pass
2. Run `npm run lint` - no errors
3. Run `npm run build` - builds successfully

Example Prompts

Test Coverage

# Task: Add Test Coverage

Add tests for all untested functions in src/utils/.

## Check Progress
- Run `npm test -- --coverage` to see coverage
- Check progress.txt for completed files

## Guidelines
- One test file per module
- Test success and error paths
- Mock external dependencies

## Completion
When coverage for src/utils/ is 80%+, output:
<promise>COMPLETE</promise>

Migration

# Task: Migrate from lodash to native

Replace lodash functions with native equivalents.

## Find work
`grep -r "import.*lodash" src/`

## Migration
- `_.map()` → `Array.map()`
- `_.filter()` → `Array.filter()`
- `_.get()` → optional chaining

## Completion
When no lodash imports remain, output:
<promise>COMPLETE</promise>

Bug Fixing

# Task: Fix Failing Tests

Fix all failing tests.

## Process
1. Run `npm test` to see failures
2. Fix one test at a time
3. Commit after each fix

## Completion
When `npm test` exits with code 0, output:
<promise>COMPLETE</promise>

Next Steps

• State Persistence — How state survives between iterations
• The Loop — Understanding the core loop mechanism