# pi-loop

`pi-loop` is the built-in helper for running the same task prompt through multiple sequential `pi` sessions.

Use it when one pass is not enough and you want later runs to reinforce, continue, verify, or refine the work from earlier runs.

## What it does

For each iteration, `pi-loop`:

- runs `pi` non-interactively in the same working tree
- prepends loop context with iteration number
- injects tail output from the previous iteration into the next prompt
- keeps going for the requested count even if the task looks mostly done
- writes per-iteration prompts, logs, status, and timestamps to a durable run directory

Default execution:

```bash
pi --provider openai-codex --model gpt-5.4-mini --thinking low --no-extensions -p ...
```

## When to use it

Use `pi-loop` when you want:

- multiple passes over the same coding task
- a simple "keep pushing this forward" loop
- cheap reinforcement without manual reprompting
- sequential refinement in the same repo state

Examples:

- implement feature, then let later passes fix gaps
- review and tighten docs after initial draft
- keep testing/refining after main code already landed

## When to use `pi-job-*` instead

Use `pi-job-*` when you want:

- one detached batch run
- explicit status/check/wait/stop lifecycle
- orchestration around one prompt, not repeated passes
- a long-running job you inspect later

Short rule:

- multiple sequential passes on same task -> `pi-loop`
- one detached inspectable batch run -> `pi-job-*`

## Usage

```bash
bin/pi-loop --count 5 --cwd /path/repo --prompt "Implement feature X"
```

```bash
bin/pi-loop --count 10 --cwd /path/repo --prompt-file ./task.txt
```

## Safe defaults

Defaults:

- provider: `openai-codex`
- model: `gpt-5.4-mini`
- thinking: `low`
- extensions: off

Override if needed:

```bash
bin/pi-loop \
  --count 3 \
  --cwd /path/repo \
  --provider openai-codex \
  --model gpt-5.4 \
  --thinking low \
  --prompt "Do the task"
```

## Output layout

Runs are stored under:

```text
/home/sebas/runtime/pi-loop-runs/<timestamp>/
```

Per iteration:

```text
iter-001/
  prompt.txt
  output.log
  status.txt
  started_at.txt
  finished_at.txt
  exit_code.txt
```

Top-level run files:

```text
base-prompt.txt
run-meta.txt
```

## Example workflow

```bash
bin/pi-loop \
  --count 3 \
  --cwd /tmp/test-repo \
  --prompt "Create or update one small file and improve it each pass"
```

Then inspect:

- repo changes in `--cwd`
- logs in `/home/sebas/runtime/pi-loop-runs/...`

## Notes

- No early-stop condition by design.
- Later iterations use current repo state as source of truth.
- `--keep-going` continues after failed iterations.
- For unattended use, prefer explicit provider/model defaults over implicit resolution.