| name | run-ralph |
| description | Start, stop, or check status of a Ralph autonomous task loop. Runs a checklist of tasks overnight — one per fresh context window, commits after each, messages progress. |
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
