pi-loops

Repeat-send a prompt to the pi agent after it finishes working and remains idle for a configured interval.

Each repeat is delivered to the agent as a real user message with a header describing the loop, so the agent can tell it is part of a repeating task:

Initial Loop created time: 2026-08-03 14:30:00
Repeat Time: 3 of 10 times
Current Loop Time: 2026-08-03 15:12:34
Loop Usage Guide: To inspect loop status, use the loop tool with action "list" (or run /loop list). To view loop documentation, use action "help" (or run /loop help).

User Task: Run the test suite and report failures.

• Initial Loop created time — when the loop was created (local time).
• Repeat Time — current repeat count (3 of 10 times when finite, 3 times when the loop is infinite).
• Current Loop Time — when this wake-up message was actually sent (local time).
• Loop Usage Guide — tells the agent how to inspect current loop status and open the loop documentation.
• User Task — the prompt you asked to repeat.

The first repeat fires immediately only when Pi is idle. If the loop is created while Pi is working, no wake-up is queued; the full interval starts after Pi settles. When any new agent work starts, the pending timer is cancelled immediately. A fresh full interval starts only after Pi settles again.

Install

pi install npm:pi-loops

Or from git:

pi install git:github.com/primp9053/pi-loops

Then restart pi (or run /reload).

This version requires @earendil-works/pi-coding-agent 0.80.4 or newer because it uses the agent_settled lifecycle event to start the idle timer only after all automatic work has finished.

Commands

/loop start <interval> <count> <prompt...>   create a loop
/loop list                                   list active loops
/loop stop <id|all>                          stop one or all loops
/loop help                                   show help

• interval — 30s, 5m, 1h, or a bare number of seconds (90). Min 1s.
• count — positive integer (number of repeats), or 0/inf for infinite.
• prompt — the rest of the line is the task to repeat.

Examples

/loop start 30s 5 Run the test suite and report failures.
/loop start 1m 0 Check git status and summarize changes.
/loop start 2m inf Summarize the latest log lines from /tmp/app.log.
/loop list
/loop stop loop-1
/loop stop all

Tool (for the LLM)

The extension also registers a loop tool the agent can call directly:

| action | parameters | description | |-----------|------------------------------------|----------------------------| | create | interval, count, prompt | start a new loop | | list | — | list active loops | | help | — | show loop documentation | | stop | id (or "all") | stop one or all loops | | stopAll | — | stop every active loop |

For create, count is a positive integer, or 0 for infinite.

Behavior notes

• Loops are in-memory and scoped to the current session. They are cleared on /reload, /new, /resume, and on quit. State is not persisted across restarts.
• After a repeat finishes all tool calls, retries, compaction, and queued follow-ups, the full interval starts. For example, with a 10-minute interval, a repeat that works for 14 minutes is followed by 10 idle minutes, so the next repeat starts about 24 minutes after the previous one started.
• Any agent_start during the idle interval immediately cancels the pending timer. The timer does not run at all while Pi is working, and agent_settled starts a new full interval.
• The extension never queues wake-up messages as follow-ups. A busy period therefore cannot accumulate loop messages or increment the repeat count.
• The active loop count is shown in the footer status line (2 loops active).
• Minimum interval is 1 second to prevent runaway flooding.

License

MIT