Run Ralph

Run Ralph — Autonomous Task Loop

Runs a markdown task file (checkboxes) as an autonomous loop. Each task gets a fresh agent with a fresh context window. After completing a task, the agent commits, the orchestrator marks it done, and schedules the next. Messages you with progress between iterations.

Starting a Run

1. Create or identify the task file

The task file is standard markdown with checkboxes:

# Feature: User Authentication

- [ ] Create user model with email and password fields
  POST /api/users table with bcrypt hashing
  Unit tests for model validation
- [ ] Add login endpoint with JWT
  POST /api/login returns token
  Returns 401 on invalid credentials
- [ ] Add registration endpoint
  POST /api/register with email verification
  Duplicate email returns 409

Rules for good task files:

• Each task must be completable in one agent session (one context window)
• Include acceptance criteria as indented lines below each checkbox
• Tasks run in order — put dependencies first
• Already-checked items [x] are skipped

2. Get the chat JID

sqlite3 store/messages.db "SELECT jid FROM registered_groups WHERE folder = 'main' LIMIT 1;"

3. Estimate iterations

Read the task file and assess each unchecked task:

Simple tasks (1 iteration each):

• Config changes, env vars, small edits
• Adding a single file or endpoint
• Running a command and reporting results

Medium tasks (2 iterations each):

• New feature with tests
• Integration with an external service
• Refactoring across multiple files

Complex tasks (3 iterations each):

• Multi-file architectural changes
• New system with several moving parts
• Anything with "and also" or multiple acceptance criteria

Add up the estimates and add 2 for retry buffer. Tell the user:

"You have N tasks. I'd estimate M iterations based on complexity:

• 3 simple (3 iterations)
• 2 medium (4 iterations)
• 1 complex (3 iterations)
• Total: 12 iterations (10 + 2 buffer)

Want me to run with that, or set a different limit?"

If the user just says "go" or "run it", use your estimate. Don't block on confirmation for small runs (under 10 iterations).

4. Start the run

Write an IPC file:

CHAT_JID="<main chat JID>"
TASK_FILE="/absolute/path/to/tasks.md"
WORK_DIR="/absolute/path/to/project"
MAX_ITER=<task count + 2>

cat > data/ipc/main/tasks/ralph_start_$(date +%s).json << EOF
{
  "type": "start_ralph",
  "taskFile": "$TASK_FILE",
  "workDir": "$WORK_DIR",
  "targetJid": "$CHAT_JID",
  "maxIterations": $MAX_ITER,
  "notifyProgress": true
}
EOF

The bot will message you: "Ralph run started: ralph-{id}"

4. Monitor progress

Between each iteration, the bot messages you:

Ralph [3/7]: Completed "Add login endpoint with JWT"

Check detailed progress:

cat data/ralph/ralph-{id}/progress.txt

Check run status:

cat data/ralph/ralph-{id}/config.json | python3 -m json.tool

Stopping a Run

CHAT_JID="<main chat JID>"
RUN_ID="ralph-{id}"

cat > data/ipc/main/tasks/ralph_stop_$(date +%s).json << EOF
{
  "type": "stop_ralph",
  "runId": "$RUN_ID",
  "targetJid": "$CHAT_JID"
}
EOF

The bot will message: "Ralph run stopped: ralph-{id}"

What happens on completion

When all tasks are checked off:

Ralph run ralph-{id} completed. 5/5 tasks done in 5 iterations.

The task file will have all checkboxes marked [x].

What happens on failure

• Task fails once: Retried on the next iteration (same task, fresh context)
• Task fails 3 times: Skipped, bot messages you, moves to next task
• Max iterations hit: Run stops, bot tells you how many tasks completed
• Service restart: Run state is on disk (data/ralph/{id}/config.json), but the current iteration's scheduled task may need re-queuing

Safety

• Each iteration runs in isolated context (fresh agent, no carried-over confusion)
• Max 10 iterations by default (configurable via maxIterations or RALPH_MAX_ITERATIONS in .env)
• Tasks that fail 3 times are skipped (configurable via maxFailuresPerTask in config.json)
• Agent is instructed to commit after each task — easy to roll back
• You can stop the loop at any time via the stop IPC command
• The task file is re-read each iteration — you can manually edit it between iterations