Install

pi install npm:@trevonistrevon/pi-loop

Quick start

LoopCreate trigger="5m" prompt="Check if the build passed"
LoopCreate trigger="tool_execution_start" prompt="Log the tool being used" triggerType="event"
LoopList
LoopDelete id="1"

MonitorCreate command="tail -n0 -f build.log" description="Watch build"
MonitorCreate command="python train.py" onDone="Analyze results and report best loss"
MonitorList
MonitorStop monitorId="1"

When pi-tasks is not installed, pi-loop also exposes native task tools after startup detection:

TaskCreate subject="Fix deploy polling" description="Switch deploy check to event-driven loop"
TaskList
TaskUpdate id="1" status="in_progress"
TaskDelete id="1"

Commands

/loop [interval] [prompt] — interactive loop creation.

/loop                         # menu
/loop 5m check the deploy     # 5-minute cron loop

/tasks — interactive native task viewer/manager, only registered when pi-tasks is absent.

/tasks                        # open native task viewer
/tasks Write README updates   # quick-create native task

Tools

| Tool | What it does | |---|---| | LoopCreate | Schedule a prompt on a cron timer, a pi event, or both with debounce | | LoopList | Show active loops with IDs, triggers, and next-fire times | | LoopDelete | Delete or pause a loop | | MonitorCreate | Run a background command, stream output as monitor:output events. Use onDone for auto-notify on completion | | MonitorList | Show monitors with status, uptime, and output line count | | MonitorStop | Stop a monitor (SIGTERM → 5s → SIGKILL) | | TaskCreate | Create a native fallback task when pi-tasks is absent | | TaskList | List native fallback tasks | | TaskUpdate | Update native fallback task status/details | | TaskDelete | Delete a native fallback task |

Trigger types: cron (5m, 1h, 0 9 * * 1-5), event (any pi event source), or hybrid (both, debounced).

Tasks

With pi-tasks

Works with @tintinweb/pi-tasks. Pass autoTask: true on LoopCreate and each loop fire auto-creates a tracked task. Detection happens over pi's event bus — no manual wiring.

Without pi-tasks

If pi-tasks does not respond during startup detection, pi-loop registers a native fallback task system for the session:

• session- or project-scoped task files under .pi/tasks/ depending on PI_LOOP_SCOPE
• TaskCreate, TaskList, TaskUpdate, TaskDelete
• /tasks interactive viewer
• compact status-line task tracking

This fallback is session-sticky: pi-loop decides once at startup whether pi-tasks or native tasks own task management for that session.

Status line

pi-loop keeps a compact persistent status line in the TUI.

When active work exists, it shows a single focus-friendly line such as:

1 loop · 1 monitor
2 tasks | active: Fix deploy polling
1 loop · 2 monitors · 3 tasks | next: Update README

When no loops, monitors, or native tasks are active, the status line clears completely.

Only task counts and the single active/next task are shown there so attention stays on what is currently happening. Use LoopList, MonitorList, and /tasks for detail.

Configuration

| Variable | Effect | Default | |---|---|---| | PI_LOOP | Store path override. off to disable, absolute or project-relative path | unset → derived from PI_LOOP_SCOPE | | PI_LOOP_SCOPE | memory (ephemeral), session (per-session file), project (shared) | session | | PI_LOOP_DEBUG | Debug logging to stderr | unset |

In session scope (default), loop and task files are saved per session ID (e.g. .pi/loops/loops-<sessionId>.json and .pi/tasks/tasks-<sessionId>.json) so concurrent sessions and worktree agents do not share state. In memory scope nothing persists to disk.

Recommended scope policy

Keep PI_LOOP_SCOPE=session as the default.

• session is the best balance for normal use: it preserves loops/tasks across a session restart while isolating concurrent sessions and worktrees.
• memory is best for disposable scratch work, tests, or situations where you explicitly do not want any persisted loop/task state.
• project should be opt-in for intentionally shared automation, because it allows multiple sessions in the same repo to see the same persisted state.

Limits

25 active loops, 25 running monitors. Recurring loops expire after 7 days.

Development

npm run typecheck
npm run lint
npm test
npm run build

See CONTRIBUTING.md.

License

MIT — LICENSE