Todo Runner

Todo Runner is for long, finite workloads where a user gives a large checklist and expects continuous execution until all items are done (or explicitly blocked).

Use cases:

• migrating dozens of modules
• batch bug-fix backlogs
• large test-remediation lists
• iterative codebase cleanups

When To Use Todo Runner vs Schedules

• Use Todo Runner for one large checklist that should run to completion.
• Use Schedules for recurring time-based prompts.

Open Todo Runner

Go to Settings -> Todo Runner.

Each job includes:

• name
• working directory
• runner command
• global prompt
• todo items (one per line)
• runtime/progress status

Create A Job

1. Click + Add Todo Run.
2. Fill in:
   • Name
   • Directory
   • Runner command (your Agent SDK worker entrypoint)
   • Global prompt (applies to every item)
   • Todo items (one per line)
3. Click Save.
4. Click Start.

Runtime Behavior

• Items run strictly in list order.
• One item is active at a time.
• Success marks item as done and advances.
• Failure retries up to 3 attempts per item.
• Failed retries use deterministic exponential cooldown (15s, 30s, 60s, capped at 5m).
• Job card surfaces the next retry timestamp when an item is cooling down.
• Item hitting max attempts becomes blocked; job pauses.
• You can Pause, Start, or Reset Progress.

Runner Contract

Agent Observer executes your runner command in the job directory and passes context through both env vars and stdin JSON.

Environment Variables

• AGENT_SPACE_TODO_PAYLOAD
• AGENT_SPACE_TODO_TEXT
• AGENT_SPACE_TODO_INDEX
• AGENT_SPACE_TODO_TOTAL
• AGENT_SPACE_TODO_PROMPT
• AGENT_SPACE_TODO_JOB_ID
• AGENT_SPACE_TODO_JOB_NAME
• AGENT_SPACE_YOLO_MODE

Stdin JSON Shape

{
  "job": {
    "id": "todo-...",
    "name": "Migration Batch",
    "prompt": "Global instruction",
    "workingDirectory": "/path/to/repo",
    "yoloMode": false
  },
  "todo": {
    "id": "item-...",
    "text": "Migrate auth middleware in packages/api",
    "index": 4,
    "total": 30,
    "attempts": 1,
    "maxAttempts": 3
  },
  "todoItems": [
    { "id": "item-...", "text": "...", "status": "done", "index": 1 }
  ]
}

Minimal Runner Expectations

Your runner should:

1. read todo payload from env or stdin
2. execute exactly one todo item per invocation
3. exit with code 0 on success
4. exit non-zero on failure with useful stderr

Todo Runner treats either non-zero exit or explicit error output as failure.

Validation Workflow

Before running a 100+ item list:

1. Test with 2 items.
2. Confirm progress increments correctly.
3. Force one failure and verify retry behavior.
4. Confirm blocked behavior after max retries.
5. Reset and start full list.

Persistence And Resume

Todo job definitions and item states are persisted locally:

• ~/.agent-observer/todo-runner.json

If the app restarts, saved state is reloaded and unfinished work can be resumed.

Failure Recovery

Job stuck in error

• Inspect Last error on the job card.
• Fix runner command or dependency issue.
• Click Start to continue from remaining items.

Wrong item execution behavior

• Verify runner consumes todo.text from payload.
• Ensure one-item-per-process contract is respected.
• Avoid internal loops that consume multiple items in one run.

Re-run from scratch

• Click Reset Progress.
• Confirm all items return to pending.
• Start again.

Next Step

For concrete Python/Node worker patterns and output contracts, see Agent SDK Runner Recipes.