📖 pi-atelier 实战指南 — 从零教会你使用 pi-atelier 扩展生态，包含完整示例和最佳实践。

English | 程序中文文档

pi-scheduler

源码仓库 | npm

Timer and recurring task extension for pi — scheduled messages, interval-based prompts, and task automation.

Why You Need It

Sometimes you need your AI agent to do things on a schedule — remind you to commit every 30 minutes, check build status periodically, or send a notification at a specific time. Without pi-scheduler, you'd have to manually trigger these actions yourself.

pi-scheduler adds time-based automation to pi:

• One-time reminders — "Remind me in 10 minutes to check the tests"
• Recurring tasks — "Every 5 minutes, check if the server is responding"
• Timed prompts — Inject messages into the agent's context at scheduled times
• Task management — List, cancel, and monitor active timers

How It Works

User/Agent: "Remind me in 10 min to check tests"
        │
        ▼
schedule(action: "create", interval_ms: 600000, prompt: "Check tests")
        │
        ▼
TimerEngine registers timer
        │
        ├── one-shot (recurring=false): fires once after interval
        └── loop (recurring=true): fires every interval
        │
        ▼ when timer fires
Prompt injected into agent context
        │
        ▼
Agent processes the prompt like a user message

Installation

pi install git:github.com/catlain/pi-scheduler

Commands

| Command | Description | |---------|-------------| | /loop | List active recurring tasks | | /remind | List active one-time reminders | | /tasks | List all active tasks (reminders + loops) |

Tool: schedule

Create, list, and cancel scheduled tasks:

| Action | Description | |--------|-------------| | create | Create a new scheduled task (one-time or recurring) | | list | List all active tasks | | cancel | Cancel a task by ID |

Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | action | string | ✅ | create, list, or cancel | | id | string | for cancel | Task ID to cancel | | prompt | string | for create | Message to inject when timer fires | | interval_ms | number | for create | Interval in milliseconds | | recurring | boolean | for create | true = repeating, false = one-shot (default) |

Examples

One-time reminder

schedule(action: "create", prompt: "Check if tests pass", interval_ms: 600000)
// Fires once after 10 minutes

Recurring task

schedule(action: "create", prompt: "Commit current changes", interval_ms: 1800000, recurring: true)
// Fires every 30 minutes

List active tasks

schedule(action: "list")

Cancel a task

schedule(action: "cancel", id: "task-abc123")

Use Cases

| Scenario | Config | |----------|--------| | Commit discipline | Recurring every 30 min: "Commit current changes" | | Monitoring | Recurring every 5 min: "Check server status" | | Time-boxing | One-shot after 60 min: "You've spent over an hour on this task" | | Build check | One-shot after 2 min: "Check if CI build passed" | | Periodic review | Recurring every 20 min: "Review what you've done so far" |

Best Practices

✅ Recommended

• Use human-readable prompts — they're injected directly into the agent's context
• Set reasonable intervals (≥ 1 minute) — too frequent will flood the context
• Use /tasks to review active tasks before creating new ones
• Cancel tasks you no longer need to free up context

❌ Not Recommended

• Don't set intervals < 30 seconds — the agent can't respond that fast
• Don't create many recurring tasks simultaneously — context pollution
• Don't use for critical scheduling — timers are lost when pi restarts

Limitations

| Limitation | Detail | |------------|--------| | No persistence | Timers are in-memory only, lost on restart | | No cron syntax | Intervals only (milliseconds), no cron expressions | | Context injection | Prompt occupies context space when it fires | | No deduplication | Creating identical tasks results in duplicates |

Architecture

pi-scheduler/
├── index.ts          # Entry: register schedule tool + slash commands
├── timer-engine.ts   # Core timer management (create/list/cancel)
├── parser.ts         # Natural language time parsing ("10 min" → ms)
├── types.ts          # Timer type definitions
├── tests/            # Unit tests
└── package.json

Dependencies:

• @earendil-works/pi-coding-agent — ExtensionAPI (peer)

License

MIT