pi-loop

A pi extension that runs a prompt repeatedly — on a fixed timer, when a pi event fires, or at the agent's own pace. Modelled on Claude Code's /loop.

Overview

Schedule a prompt to run repeatedly inside pi. An interval is parsed at the command layer into a cron schedule and run by a self-re-arming timer, so the loop keeps going on its own — the model is never responsible for keeping it alive. A self-paced mode is kept for "let the model decide when there's nothing left to do."

What changed in 0.2.0

Earlier versions had a single self-paced mode: the model had to call a wakeup tool at the end of every turn or the loop ended. That meant a turn ending on a summary silently killed the loop, and an interval like 15m written in the prompt was never actually a cadence — just text.

0.2.0 makes a parsed interval authoritative and timer-driven, adds event and hybrid triggers, multiple concurrent loops, and persistence that restores unexpired loops on resume. Self-paced remains as a second mode.

Features

• Fixed-interval loops — /loop 15m <prompt> parses the interval into cron and runs it on a self-re-arming timer. Continuation is the default.
• Self-paced loops — /loop <prompt> (no interval) fires once, then continues only if the model calls schedule_loop_wakeup. It may end the loop by not calling it.
• Event & hybrid triggers — fire on a pi event (e.g. tool_execution_end, turn_end, monitor:done) instead of polling, or combine cron + event with debounce.
• Multiple loops — run several at once; manage with LoopCreate / LoopList / LoopDelete or /loop list.
• Persistence — loops are stored under .pi/loops and restored, if unexpired, on --resume/--continue.
• Safety caps — per-loop maxFires and an automatic 7-day expiry; jittered fire times avoid API stampedes.
• Read-only mode — restrict a loop's fires to read/inspection tools.
• Live status — a footer indicator and widget list active loops with next-fire countdowns.

Installation

pi install npm:@koltmcbride/pi-loop
# or
pi install git:github.com/kolt-mcb/[email protected]

Verify it's loaded with pi list.

Quick start

/loop 5m check if the deployment finished and report what happened

Fixed 5-minute loop. Runs until you stop it, 7 days pass, or it hits a fire cap.

/loop check whether CI passed and address review comments

Self-paced: the model works, then decides whether to continue via schedule_loop_wakeup (and at what delay).

/loop stop          # stop all active loops
/loop stop 3        # stop loop #3
/loop list          # show / manage active loops

Usage

/loop command

| Input | Behaviour | |---|---| | /loop 15m <prompt> | Fixed-interval (cron) loop. Interval may also trail: <prompt> every 2 hours. | | /loop 0 9 * * 1-5 <prompt> | Full 5-field cron schedule. | | /loop <prompt> | Self-paced loop (model-driven cadence). | | /loop list | List/manage active loops. | | /loop stop [id] | Stop all loops, or one by id. |

Intervals use s / m / h / d. Sub-minute rounds up to one minute (cron's floor); odd intervals like 7m snap to the nearest clean cron step and the loop tells you what it picked.

Tools (for the agent)

| Tool | What it does | |---|---| | LoopCreate | Schedule a loop on a cron timer, a pi event, or a hybrid of both. Supports recurring, readOnly, maxFires, filter. | | LoopList | List loops with ids, triggers, fire counts, next-fire times. | | LoopDelete | Delete a loop, or action="pause" to keep it without firing. | | schedule_loop_wakeup | Continue the active self-paced loop; optional delaySeconds. Omit to end it. |

Trigger types: cron (5m, 1h, 0 9 * * 1-5), event (any pi event-bus channel; lifecycle events tool_execution_start/end, turn_start/end, agent_start/end, message_end are bridged through), or hybrid (both, debounced).

Behaviour notes

• Fires land between turns. Each fire is delivered as a follow-up message, so it waits for the current turn to finish. A recurring fire is skipped while a message is already queued, so ticks never stack.
• Takeover. Typing while a self-paced loop is waiting ends it (you took over). Fixed and event loops keep running across your messages until you /loop stop them.
• No catch-up. If fires were missed while busy, the loop fires once when idle, not once per missed interval.

Configuration

| Variable | Effect | Default | |---|---|---| | PI_LOOP | off disables persistence (in-memory only); an absolute or relative path sets a custom store file | .pi/loops/loops-<sessionId>.json |

Constants at the top of loop.ts / src/: status tick interval, default hybrid debounce, and the bridged lifecycle event list. Caps: 25 active loops, 7-day expiry.

Development

npm install
npm run typecheck   # tsc --noEmit
npm test            # node:test via tsx — covers parsing, cron, jitter

Source layout:

| File | Responsibility | |---|---| | src/types.ts | Loop/trigger types. | | src/loop-parse.ts | parseInterval, extractInterval, cron math, jitter (pure, tested). | | src/store.ts | Loop registry + JSON persistence. | | src/scheduler.ts | Self-re-arming cron timers. | | src/triggers.ts | Event/hybrid subscriptions + debounce. | | loop.ts | Entry: command, tools, fire→message bridge, status widget, lifecycle. |

License

MIT