{"id":48001819,"url":"https://github.com/tintinweb/pi-schedule-prompt","last_synced_at":"2026-05-01T14:00:55.015Z","repository":{"id":338774624,"uuid":"1157011405","full_name":"tintinweb/pi-schedule-prompt","owner":"tintinweb","description":"A Pi extension that lets the AI agent schedule, defer, and remind you by executing prompts at specific times or intervals.","archived":false,"fork":false,"pushed_at":"2026-05-01T00:41:50.000Z","size":5868,"stargazers_count":41,"open_issues_count":7,"forks_count":7,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-01T02:18:57.274Z","etag":null,"topics":["pi-agent","pi-extension","pi-package"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/pi-schedule-prompt","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tintinweb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-13T10:17:50.000Z","updated_at":"2026-04-29T18:25:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tintinweb/pi-schedule-prompt","commit_stats":null,"previous_names":["tintinweb/pi-schedule-prompt"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/tintinweb/pi-schedule-prompt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tintinweb%2Fpi-schedule-prompt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tintinweb%2Fpi-schedule-prompt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tintinweb%2Fpi-schedule-prompt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tintinweb%2Fpi-schedule-prompt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tintinweb","download_url":"https://codeload.github.com/tintinweb/pi-schedule-prompt/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tintinweb%2Fpi-schedule-prompt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32499691,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["pi-agent","pi-extension","pi-package"],"created_at":"2026-04-04T12:23:35.277Z","updated_at":"2026-05-01T14:00:54.991Z","avatar_url":"https://github.com/tintinweb.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pi-schedule-prompt\n\nA \"Heartbeat\" like prompt scheduling [Pi](https://pi.dev) extension that allows the Agent to self-schedule future prompts to execute at specific times or intervals - for reminders, deferred tasks, and recurring automation.\n\n\n\u003cimg width=\"600\"  alt=\"image\" src=\"https://github.com/tintinweb/pi-schedule-prompt/raw/master/media/screenshot.png\" /\u003e\n\n\n\n\nhttps://github.com/user-attachments/assets/8c723cc4-cf3e-4b6a-abf5-85d4f46c73ba\n\n\u003e **Status:** Production-ready. Natural language scheduling with cron expressions, intervals, relative time, and one-shot timers.\n\nSchedule future prompts with natural language:\n- **\"schedule 'analyze logs' every hour\"** (recurring)\n- **\"remind me to review PR in 30 minutes\"** (one-time)\n- **\"defer that task until tomorrow at 9am\"** (specific time)\n\n## Features\n\n### Core `schedule_prompt` Tool\n- **Natural language scheduling**: \"schedule X in 5 minutes\", \"every hour do Y\"\n- **Multiple formats**: Cron expressions, intervals, ISO timestamps, relative time (+5m, +1h)\n- **Job types**: \n  - **Recurring** (cron/interval) — repeats automatically\n  - **One-shot** (once) — runs once then auto-disables\n- **Per-task model (optional)**: set `model` on a job to run that prompt in a separate in-process agent session — your current chat is not affected\n- **Actions**: add, remove, list, enable, disable, update, cleanup\n- **Auto-cleanup**: Removes disabled jobs on session exit\n\n### Use Cases\n\n#### Schedule (Recurring Tasks)\nExecute prompts repeatedly at set intervals:\n```\n\"schedule 'check build status' every 5 minutes\"\n\"run 'analyze metrics' every hour\"\n\"execute 'daily summary' at midnight every day\"\n```\n\n#### Remind (One-time Notifications)\nGet prompted to do something once at a specific time:\n```\n\"remind me to review the PR in 30 minutes\"\n\"remind me to check deployment status in 1 hour\"\n\"remind me tomorrow at 9am to follow up on the issue\"\n```\n\n\n### Enhanced Pi Features\n- ✓ **Live widget** below editor showing active schedules (auto-hides when empty)\n- ✓ **Human-readable display**: \"every minute\", \"daily at 9:00\" instead of raw cron expressions\n- ✓ **Status tracking**: next run, last run, execution count, errors, prompt preview\n- ✓ **Flexible scheduling**: 6-field cron, intervals (5m, 1h), relative time (+10s), ISO timestamps\n- ✓ **User commands**: `/schedule-prompt` interactive menu with a `Settings` submenu (current state visible in the row label)\n- ✓ **Persistent settings**: widget visibility persists across sessions and package upgrades (project file overrides global defaults)\n- ✓ **Safety features**: duplicate name prevention, infinite loop detection, past timestamp handling\n\n## Install\n\n**Option A — Install from npm:**\n```bash\npi install npm:pi-schedule-prompt\n```\n\n**Option B — Load directly (dev):**\n```bash\npi -e ~/projects/pi-cron-schedule/src/index.ts\n```\n\n**Option C — Install from local folder:**\n```bash\npi install ~/projects/pi-cron-schedule\n```\n\nThen run `pi` normally; the extension auto-discovers.\n\n## Usage\n\n### LLM-driven (automatic)\n\nThe agent automatically uses `schedule_prompt` when you want to schedule, defer, or be reminded:\n\n```\nYou: Remind me to check the deployment logs in 10 minutes\n\nAgent: [calls schedule_prompt with schedule=\"+10m\", prompt=\"check the deployment logs\"]\n✓ Scheduled job \"abc123\" to run in 10 minutes\n```\n\nThe widget displays below your editor (only when jobs exist):\n\n```\n Scheduled Prompts (3 jobs)\n  ✓ check-logs    every hour      check deployment logs     in 45m    12m ago  5\n  ✗ daily-report  daily           analyze metrics           in 8h     never    0\n  ✓ review-pr     Feb 13 15:30    review PR #123            in 2h     never    0\n```\n\n### Manual commands\n\n| Command | Description |\n|---------|-------------|\n| `/schedule-prompt` | Interactive menu: view/add/toggle/remove jobs, cleanup, and `Settings` submenu (widget visibility, etc.) |\n\n### Tool Parameters (`schedule_prompt`)\n\n| Param | Type | Required | Description |\n|-------|------|----------|-------------|\n| `action` | `add` \\| `remove` \\| `list` \\| `enable` \\| `disable` \\| `update` \\| `cleanup` | yes | Operation to perform |\n| `name` | string | no | Job name (auto-generated if omitted on `add`) |\n| `schedule` | string | on `add` | Cron expression, ISO timestamp, relative time (`+10s`, `+5m`), or interval (`5m`) |\n| `prompt` | string | on `add` | Prompt text to execute when the job fires |\n| `jobId` | string | on `remove` / `enable` / `disable` / `update` | Target job |\n| `type` | `cron` \\| `once` \\| `interval` | no | Job type. Default `cron`; use `once` for relative times like `+10s` |\n| `description` | string | no | Free-form note |\n| `model` | non-empty string | no | If set, run the prompt in a fresh in-process agent session with this model instead of injecting into the current chat. Accepts fuzzy names (`haiku`, `sonnet`) or `provider/model-id`. To switch a job from subagent back to inline mode, remove and re-add it without `model` (no in-place clearing) |\n| `notify` | boolean | no | Subagent-only. If `true`, the parent agent is woken to react to the subagent's result. Default `false` (result shown in chat, parent not interrupted). No-op for inline (no-model) jobs — the prompt itself already wakes the parent. Recommended only for low-frequency jobs |\n\n### Schedule Formats\n\nThe tool accepts multiple time formats:\n\n| Format | Example | Type | Description |\n|--------|---------|------|-------------|\n| **Relative time** | `+5m`, `+1h`, `+30s`, `+2d` | once | Runs once after delay |\n| **Interval** | `5m`, `1h`, `30s`, `2d` | interval | Repeats at interval |\n| **ISO timestamp** | `2026-02-13T15:30:00Z` | once | Runs once at exact time |\n| **Cron expression** | `0 */5 * * * *` | cron | Runs on cron schedule |\n\n**Cron format** (6 fields - **must include seconds**):\n```\n┌─ second (0-59)\n│ ┌─ minute (0-59)\n│ │ ┌─ hour (0-23)\n│ │ │ ┌─ day of month (1-31)\n│ │ │ │ ┌─ month (1-12)\n│ │ │ │ │ ┌─ day of week (0-6, Sun-Sat)\n│ │ │ │ │ │\n0 * * * * *   → every minute\n0 0 * * * *   → every hour\n0 */5 * * * * → every 5 minutes\n0 0 0 * * *   → daily at midnight\n0 0 9 * * 1-5 → 9am on weekdays\n* * * * * *   → every second\n```\n\n**Note:** Traditional 5-field cron expressions (without seconds) are not supported. Use `0 * * * * *` for \"every minute\", not `* * * * *`.\n\n## How It Works\n\n**Storage:**\n- Job data: `.pi/schedule-prompts.json` (project-local, atomic writes, auto-created)\n- Settings: two-layer config — `~/.pi/agent/schedule-prompts-settings.json` (global, hand-edited defaults) and `\u003ccwd\u003e/.pi/schedule-prompts-settings.json` (project, written by the UI). Project overrides global on load.\n\n**Scheduler:**\n- Uses `croner` library for cron expressions\n- Native `setTimeout`/`setInterval` for intervals and one-shots\n- Tracks: next run, last run, execution count, status (running/success/error)\n\n**Execution:**\n- Sends scheduled prompt as user message to Pi agent\n- Displays custom message showing what was triggered\n- Updates job statistics after each run\n\n**Safety:**\n- **Infinite loop prevention**: Blocks scheduled jobs from creating more schedules\n- **Past timestamp detection**: Auto-disables jobs scheduled in the past\n- **Duplicate names**: Prevents name collisions\n- **Auto-cleanup**: Removes disabled jobs on exit\n\n**Widget:**\n- Auto-hides when no jobs configured\n- Shows: status icon, name, schedule (human-readable), prompt (truncated), next run, last run, run count\n- Human-readable formatting: \"every minute\", \"daily\", \"Feb 13 15:30\" instead of raw cron/ISO\n- Auto-refreshes every 30 seconds\n- Visibility togglable via `/schedule-prompt → Settings`; persists across sessions (and package upgrades) in `\u003ccwd\u003e/.pi/schedule-prompts-settings.json`, with `~/.pi/agent/schedule-prompts-settings.json` as the global default\n- Status icons: `✓` enabled, `✗` disabled, `⟳` running, `!` error\n\n## Examples\n\n### One-time reminders\n```\n\"remind me to check logs in 5 minutes\"\n  → schedule=\"+5m\", type=once\n\n\"schedule 'review metrics' for 3pm today\"\n  → schedule=\"2026-02-13T15:00:00Z\", type=once\n```\n\n### Recurring tasks\n```\n\"analyze error rates every 10 minutes\"\n  → schedule=\"10m\", type=interval\n\n\"run daily summary at midnight\"\n  → schedule=\"0 0 0 * * *\", type=cron\n\n\"check build status every hour\"\n  → schedule=\"0 0 * * * *\", type=cron\n\n\"execute every minute\"\n  → schedule=\"0 * * * * *\", type=cron\n```\n\n### Heartbeat monitoring\n```\n\"check system health every 5 minutes\"\n  → schedule=\"5m\", type=interval\n```\n\n### Run in a separate agent session (per-task model)\n\nBy default a scheduled prompt is injected into your current chat. Set `model` on the job to run it in a fresh in-process agent session instead — your current chat keeps its own model and context untouched.\n\n```\n\"every morning at 9, summarise yesterday's logs using haiku\"\n  → schedule=\"0 0 9 * * *\", type=cron, model=\"haiku\", prompt=\"summarise yesterday's logs\"\n\n\"in 30s reply with OK using sonnet\"\n  → schedule=\"+30s\", type=once, model=\"sonnet\", prompt=\"Reply with OK\"\n```\n\n`model` is permissive: pass a fuzzy name (`haiku`, `sonnet`) or fully qualified `provider/model-id`. The first match in the available model registry is used. When the job fires you'll see a `🕐 Scheduled (subagent: \u003cmodel\u003e)` marker in chat, followed by a `✓ finished` (or `✗ failed`) marker with the response snippet once the subagent completes.\n\nBy default the result is shown in chat but the parent agent is **not** woken up — you read it, the agent isn't interrupted. Set `notify: true` on the job if you want the parent to react to each completion (e.g. for autonomous workflows). Recommended only for low-frequency jobs; a `notify: true` recurring job that fires every 5 minutes will trigger a parent-agent turn every 5 minutes.\n\n\u003e **Heads up:** Subagent jobs run unattended at fire time with the full default tool set (`bash`, `read`, `edit`, `write`, …) under your credentials. Treat persisted jobs in `.pi/schedule-prompts.json` as you would any auto-executed task — review prompts before adding, especially anything that mutates files or shells out.\n\n## Development\n\n**TypeScript check:**\n```bash\nnpx tsc --noEmit\n```\n\n**Run the test suite (vitest):**\n```bash\nnpm test\n```\n\n**Test with Pi:**\n```bash\npi -e ./src/index.ts\n```\n\n## Project Structure\n\n```\nsrc/\n  types.ts          # CronJob, CronJobType, CronToolParams\n  storage.ts        # Job persistence (.pi/schedule-prompts.json)\n  settings.ts       # Settings persistence (global + project, project overrides)\n  scheduler.ts      # Core scheduling engine with croner\n  subagent.ts       # Lightweight in-process agent runner (per-task model)\n  tool.ts           # schedule_prompt tool definition\n  ui/\n    cron-widget.ts  # Live status widget below editor\n  index.ts          # Extension entry point\n```\n\n## License\n\nMIT (see [LICENSE](LICENSE))\n\n## Author\n\n[tintinweb](https://github.com/tintinweb)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftintinweb%2Fpi-schedule-prompt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftintinweb%2Fpi-schedule-prompt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftintinweb%2Fpi-schedule-prompt/lists"}