pi-loop

A Pi coding-agent extension that adds a /loop command — run a prompt repeatedly, confirming between rounds, exactly like the Claude Code CLI /loop, but with a richer set of stop conditions, lifecycle hooks, a live TUI panel, and desktop notifications.

╭────────────────────────────────────────────╮
│ ⟳ /loop  iter 3/5                          │
│ ███████████████░░░░░ 60%                   │
│ ⠴ idle   12.3s                            │
│ tag    build                              │
│ conv   ████████░░ 82%                      │
│ ↳ refactored the loop panel for clarity    │
│ ⊘ /loop stop to cancel                     │
╰────────────────────────────────────────────╯

---

Features

• Repeat a prompt with optional per-round confirmation (manual mode) or fully unattended (YOLO autopilot).
• Stop conditions: text match, regex match, all-match, identical-reply convergence, fuzzy convergence, single-step similarity threshold, external command success/failure, wall-clock timeout, per-iteration timeout, error markers, and max failures.
• Self-referential prompts via rich templating: {{n}}, {{prev}}, {{prev:N}}, {{last:N}}, {{all}}, {{count}}, {{ts}}.
• Lifecycle hooks (--on-start / --on-fail / --on-stop / --on-iter) to drive external automation (CI, notifications, logging).
• Rich live TUI panel: animated boxed status with progress bar, phase indicator, ETA, convergence bar, and a last-reply preview.
• Resilience: exponential-backoff retries on error markers, a bounded default turn timeout (so a stuck agent can never hang the loop forever), and a single-loop concurrency guard.
• Run logs: every loop writes a JSON log to ~/.pi/loops/ (last 20 kept); browse them with logs, stats, show.
• Presets: save/load named loop configs; /loop with no args resumes the last run.
• Finish signals: --notify (OS toast) and --sound (terminal bell).

---

Requirements

• Pi coding agent installed and running.
• Node.js 18+ (Pi's runtime).

---

Install

@realvendex/pi-loop is a Pi package: it ships a pi manifest that tells Pi to load index.ts as an extension. Pick one method — do not combine them, or /loop gets registered twice and Pi warns about a duplicate command.

Option A — pi install (recommended)

pi install npm:@realvendex/pi-loop          # latest
pi install npm:@realvendex/pi-loop@1.0.1    # or pin a version

Pi installs the package under ~/.pi/agent/npm/ and auto-loads the extension from its pi manifest. Run /reload (or restart Pi) to activate it. Update later with pi update npm:@realvendex/pi-loop.

Option B — git clone

git clone https://github.com/ZachDreamZ/pi-loop /tmp/pi-loop
cp /tmp/pi-loop/extensions/index.ts ~/.pi/agent/extensions/pi-loop/index.ts

Then run /reload (or restart Pi). No build step — Pi loads index.ts directly from the extensions directory.

Option C — npm + manual copy

npm i -g @realvendex/pi-loop
# copy the extension entry into Pi's extension directory
cp "$(npm root -g)/@realvendex/pi-loop/index.ts" ~/.pi/agent/extensions/pi-loop/index.ts
/reload

Local install works too: npm i @realvendex/pi-loop then copy node_modules/@realvendex/pi-loop/index.ts into the extensions directory.

---

Quick start

/loop "fix the failing tests" --max 5
/loop --yes --until "all tests pass" "refactor the auth module"
/loop "attempt {{n}}: {{prev}}" --max 5 --yes
/loop --yes --until-stable 3 "tweak until output converges"
/loop --until-converged 95 --max 20 "iterate until replies stop changing"
/loop --until-regex "tests:\s+\d+ passing" --yes "run the suite"
/loop --timeout 5m "long autonomous task"
/loop --name deploy --yes "ship it"        # tagged run log
/loop --notify --sound --yes --max 5 "do the work"   # toast + bell on finish
/loop                                      # resume the last loop
/loop stop                                 # cancel the active loop

---

Commands

Command	Description
/loop "<prompt>" [flags]	Run a loop (the main command).
/loop stop	Cancel the active loop (halts after the current iteration).
/loop resume	Re-run the last /loop invocation (also: bare /loop).
/loop save NAME	Save the last run's config as a named preset.
/loop load NAME	Run a saved preset (alias: /loop run NAME).
/loop list	List all saved presets and the last config.
/loop delete NAME	Delete a saved preset.
/loop last	Print the most recent loop config.
/loop logs [TAG]	List recent run logs (most recent first), optionally filtered by a --name tag.
/loop stats	Aggregate metrics across all run logs (count, avg iterations, avg duration, stop-reason breakdown).
/loop show [N]	View a run log. N = index (1 = most recent), a filename, or a substring.
/loop preview "<prompt> ...flags>"	Print the resolved config and every templated prompt (up to 10) without running — great for debugging templates.

---

Flags

Flag	Default	Description
--max N / -n N	10	Maximum iterations. --max 0 = unbounded (runs until a stop condition, --timeout, or /loop stop).
--until "TEXT"	—	Stop when the last assistant reply contains TEXT. Repeatable (any match stops).
--until-regex R	—	Stop when the last assistant reply matches regex R. Repeatable. Invalid patterns are ignored with a warning.
--until-all / --all	off	Require ALL --until texts AND --until-regex patterns to match (default: ANY match stops).
--until-stable N	0	Stop when the last N consecutive replies are identical (convergence).
--until-stable-sim P / --stable-sim P	0	Fuzzy convergence: last N replies must be ≥P similar (token-overlap, 0..1) instead of byte-identical.
--until-converged P / --converge P	0	Stop when the single-step similarity between the last two replies is ≥ P% (0–100). Distinct from --until-stable-sim, which requires a window of N replies.
--yes / -y / --auto / --yolo	off	YOLO autopilot: skip per-round confirmation and auto-approve any confirmation surfaced during a turn. Never blocks.
--delay MS / --every MS	0	Milliseconds to wait between iterations.
--delay-jitter P	0	Apply ±P% random jitter to --delay (0..100) to avoid rate-limit clumping.
--timeout 30s|5m|1h	0	Wall-clock cap; loop stops when exceeded (units s/m/h, or bare seconds).
--iter-timeout 30s|5m|1h	0	Per-iteration cap; if a single turn exceeds it, the loop stops. When unset, a 30-minute default bound still applies so a stuck turn can't hang the loop forever.
--stop-on-error	off	Stop if the last assistant reply shows an error marker.
--retry-on-error N / --retry N	0	Retry a failed iteration up to N times (nudges the agent to try a different approach) before stopping.
--retry-delay MS	1000	Base delay between retries; grows exponentially (MS, 2·MS, 4·MS … capped at 60s).
--max-failures N	0	Stop after N consecutive failed iterations (error marker with no retry left, and --stop-on-error not set).
--until-cmd C / --until-command C	—	Stop when shell command C exits 0 (e.g. run your test suite; loop until it passes). Checked once before iteration 1 and after every iteration; 120s timeout (override with --until-cmd-timeout).
--until-cmd-fail C / --until-command-fail C	—	Inverse: stop when shell command C exits non-zero (e.g. loop while a server is up; stop the moment it goes down).
--until-cmd-timeout T	120s	Timeout for --until-cmd / --until-cmd-fail (units s/m/h, or bare ms).
--on-start CMD	—	Run shell CMD once, just before iteration 1 (skipped if a pre-flight check already ends the loop). Tokens: {{i}} {{max}} {{name}}.
--on-fail CMD	—	Run shell CMD after each failed iteration. Tokens: {{i}} {{reply}} {{reason}}.
--on-stop CMD	—	Run shell CMD once when the loop ends (any reason). Tokens: {{i}} {{reason}} {{iterations}} {{reply}}.
--on-iter CMD	—	Run shell CMD after every completed iteration. Tokens: {{i}} {{reply}} {{reason}}.
--hook-timeout T	30s	Timeout for hook commands; a hung hook is killed and reported as a warning, never aborting the loop.
--error-markers A|B	built-ins	Custom pipe-delimited error markers (overrides the built-in list).
--name TAG	—	Tag the run-log filename (e.g. loop-deploy-<ts>.json) for easy lookup.
--quiet / -q	off	Suppress per-iteration start notices.
--notify	off	Show an OS notification (macOS / Linux / Windows) when the loop finishes.
--sound	off	Play a terminal bell when the loop finishes.

---

Prompt templating

Before each send, these tokens are substituted into the prompt (unknown tokens are left untouched):

Token	Substituted with
{{n}} / {{N}} / {{i}}	1-based iteration number
{{max}} / {{MAX}}	Total iteration cap, or ∞ when --max 0 (unbounded)
{{prev}} / {{prev1}}	The previous assistant reply (whitespace collapsed, truncated to 500 chars)
{{prev:N}}	The Nth-previous reply (2 = the one before {{prev}})
{{last:N}}	The last N characters of the previous reply
{{all}}	All prior replies joined by ---
{{count}}	Number of completed prior iterations
{{ts}}	Current timestamp at render time (ISO 8601, fresh per iteration)

Example — each iteration builds on everything that came before:

/loop --yes --max 8 "Iteration {{n}} of {{max}} ({{count}} prior attempts).\nPrior work:\n{{all}}\nNow improve it."

---

Lifecycle hooks

Hooks let a loop drive external automation at key moments. Each hook is a shell command; Pi substitutes {{token}} vars before running it and reports the output via a notification. A hook that errors or times out is reported as a warning and never stops the loop.

Hook	When it fires	Available tokens
--on-start CMD	Once, before iteration 1 (only if the loop actually runs)	{{i}} (=0), {{max}}, {{name}}, {{reason}}
--on-fail CMD	After each failed iteration (error marker, no retry remaining)	{{i}}, {{n}}, {{max}}, {{name}}, {{reason}} (=error-marker), {{reply}}, {{prev}}
--on-stop CMD	Once, when the loop ends (any reason)	{{i}}, {{n}}, {{max}}, {{name}}, {{reason}} (stop cause), {{iterations}}, {{reply}}, {{prev}}
--on-iter CMD	After every completed iteration (next-iteration path)	{{i}}, {{n}}, {{max}}, {{name}}, {{reason}} (=iteration), {{reply}}, {{prev}}

Shared hook tokens: {{i}}/{{n}} (iteration), {{max}} (cap or ∞), {{name}} (tag), {{reason}} (stop cause: max, until, error, timeout, cmdfail, maxfailures, stable, converged, …), {{reply}} (latest reply), {{prev}} (prior reply), {{iterations}} (total run). Control hook runtime with --hook-timeout (default 30s).

/loop --yes --max 5 --on-stop "curl -s ntfy.sh/mytopic -d 'loop done: {{reason}}'" "build the thing"
/loop --yes --until-cmd "npm test" --on-fail "echo 'FAILED iter {{i}}: {{reply}}' >> /tmp/loop-fails.log" "fix the tests"
/loop --yes --max 3 --on-start "echo loop started for {{name}}" --name nightly "run the job"

---

Behavior

• Manual mode (default): after each iteration Pi asks you to continue. Decline (or press Escape) to stop.
• Autopilot mode (--yes / --auto / --yolo): runs unattended and auto-approves every prompt. Still stops on --max, --timeout, --iter-timeout, a --until match, convergence, or an error marker when --stop-on-error is set.
• Cancel anytime: send /loop stop. The loop halts after the current iteration completes (it never kills a turn mid-flight).
• A rich live TUI panel shows the current iteration, progress, phase, ETA, convergence, and last-reply snippet. The final summary reports the stop reason, total time, average time per iteration, and convergence percentage.
• Every loop writes a JSON run log to ~/.pi/loops/ (last 20 kept).

---

Notes

• Only one loop runs at a time. Starting a new /loop while one is active is blocked until you send /loop stop.
• The loop sends real user messages via pi.sendUserMessage, so the agent behaves exactly as if you typed the prompt each round.
• In non-interactive contexts (no UI), manual confirmation is unavailable, so the loop automatically switches to autopilot with a warning.

---

Development

git clone https://github.com/ZachDreamZ/pi-loop
cd pi-loop
npm install        # pulls typescript + @types/node for type-checking
npm run typecheck  # tsc --noEmit (validates the extension in isolation via a type shim)

extensions/index.ts is the entire extension. Pi loads it directly (no build step). The type shim in shims/pi-coding-agent.d.ts lets tsc type-check the file without the Pi binary. CI runs npm run typecheck on every push/PR.

---

License

MIT © ZachDreamZ