@pi-agents/loop

Recurring prompt scheduling and cron job management for pi-coding-agent. Ported from Claude Code's /loop system.

Features

• /loop command — Fixed interval (/loop 5m check the deploy) or dynamic self-pacing (/loop monitor the build)
• Cron tools — LLM-callable cron_create, cron_delete, cron_list for programmatic scheduling
• ScheduleWakeup — schedule_wakeup tool for model-driven dynamic pacing (60-3600s delays)
• Idle gating — Prompts only fire when the agent is idle, never interrupting in-progress work
• Durable tasks — Optionally persist schedules across sessions via .pi-loop.json
• Missed task recovery — Durable one-shots missed while offline are detected and fired on restart
• Session resume — Session-only tasks survive conversation compaction
• Anti-thundering-herd — Deterministic jitter (50% of interval, 30-min cap) prevents API load spikes
• Auto-expiry — Recurring tasks expire after 7 days by default
• Config files — Per-project .pi-loop.config.json overrides
• Debug mode — Set PI_LOOP_DEBUG=1 for verbose logging

Install

pi install npm:@pi-agents/loop@latest

Or add to your pi-agent settings (~/.pi/agent/settings.json):

{
  "packages": ["npm:@pi-agents/loop"]
}

Usage

Slash Commands

| Command | Description | |---|---| | /loop [interval] <prompt> | Start a recurring loop (default: dynamic pacing) | | /loop-list | List all active loops | | /loop-kill <id> | Cancel a loop by ID |

Fixed interval:

/loop 5m check the deploy
/loop check tests every 15m

Dynamic pacing (no interval):

/loop monitor the build

The agent executes the prompt immediately, then uses schedule_wakeup to self-pace subsequent iterations.

LLM Tools

The extension registers four tools the LLM can call directly:

| Tool | Description | |---|---| | cron_create | Schedule a prompt on a 5-field cron expression | | cron_delete | Cancel a scheduled task by ID | | cron_list | List all active scheduled tasks | | schedule_wakeup | Arm a single-shot timer for dynamic self-pacing |

cron_create parameters:

| Parameter | Type | Default | Description | |---|---|---|---| | cron | string | required | 5-field cron expression in local time | | prompt | string | required | Prompt to enqueue at fire time | | recurring | boolean | true | true = recurring, false = one-shot | | durable | boolean | false | true = persist across sessions | | label | string | optional | Human-readable label |

schedule_wakeup parameters:

| Parameter | Type | Description | |---|---|---| | delaySeconds | number | Seconds until wake-up (clamped to 60-3600) | | reason | string | Why this delay was chosen | | prompt | string | Prompt to fire on wake-up |

Cron Format

Standard 5-field cron in local time: minute hour day-of-month month day-of-week

| Pattern | Meaning | |---|---| | */5 * * * * | Every 5 minutes | | 0 */2 * * * | Every 2 hours | | 30 14 * * * | Daily at 2:30 PM | | 0 9 * * 1-5 | Weekdays at 9 AM |

Durable vs Session Tasks

• Session tasks (default) — Live only for the current session. Survive compaction. Lost when the agent exits.
• Durable tasks (durable: true) — Persisted to .pi-loop.json. Restored on next session start. Missed one-shots are recovered and fired.

Multi-Instance Safety

When multiple pi-agent sessions run in the same directory, a file-based lock (.pi-loop.json.lock) ensures only one instance processes durable tasks. Uses PID-based liveness checking to recover from crashed sessions.

Configuration

Create .pi-loop.config.json in your project root to override defaults:

{
  "maxJobs": 50,
  "recurringMaxAgeMs": 604800000,
  "durableFilePath": ".pi-loop.json"
}

| Setting | Default | Description | |---|---|---| | maxJobs | 50 | Maximum concurrent scheduled tasks | | recurringMaxAgeMs | 604800000 (7d) | Auto-expiry for recurring tasks | | recurringJitterFrac | 0.5 | Jitter as fraction of cron gap (50%) | | recurringJitterCapMs | 1800000 (30m) | Maximum jitter delay | | checkIntervalMs | 1000 | Scheduler tick interval | | durableFilePath | .pi-loop.json | Durable task file path |

Development

npm run build       # Compile TypeScript
npm run test        # Run all tests (unit + integration)
npm run test:unit   # Run unit tests only
npm run test:watch  # Watch mode

License

MIT