# ralph-loop-run

`ralph-loop-run` is a blocking sequential orchestrator for repeated `pi` agent passes that must hand off only through files.

## Use when

- you want a fixed number of sequential agent runs
- you want hardcoded runner logs for each step
- you want agents to communicate only through `TASKS.md` and `STATE.md`
- you want control returned only after the full loop finishes

## Usage

```bash
/home/sebas/pi-config/bin/ralph-loop-run \
  --repo /home/sebas/work/projects/ballbox \
  --tasks-file /path/to/tasks.md \
  --count 10
```

## Run layout

```text
/home/sebas/runtime/ralph-loops/<timestamp>/
  TASKS.md
  STATE.md
  run-meta.txt
  runner.log
  iterations/
    iter-001/
      prompt.txt
      output.log
      status.txt
      started_at.txt
      finished_at.txt
      exit_code.txt
```

## Runner behavior

Per iteration the runner logs:

1. prompt built
2. launching pi
3. pi finished ok/failed
4. state after iteration

## Agent contract

Each iteration is instructed to:

- read `TASKS.md` and `STATE.md`
- choose the highest-value pending task
- update those files before exit
- work only in the target repo
- avoid push/merge/user questions

## Notes

- default provider/model/thinking match the local batch defaults
- this is a blocking orchestrator, not a detached job helper
- if you want detached lifecycle commands, use `pi-job-*` instead