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?"