@bacnh85/pi-cron
Scheduled jobs for Pi — cron-style jobs that fire a prompt into the live session while pi is running, with past-due catch-up and crontab export for 24/7 coverage.
Install
pi install @bacnh85/pi-cron
Usage
The cron tool (and /cron command) manages jobs stored in
<agentDir>/cron/jobs.json:
| Action | What it does |
|---|---|
add | Create a job: name, schedule (5-field cron), prompt (fired as a standalone turn), optional cwd, optional model / thinking pins. |
remove | Delete a job by name. |
list | Show name, schedule, next/last fire, enabled, last run status ([ok] / [FAIL: reason]), model pin. |
run | Fire a job manually right now (also the retry for a failed job). |
enable / disable | Toggle a job. disable pauses (schedule kept; skipped by ticks and export); enable recomputes the next fire from now — no surprise catch-up fire. add also accepts enabled:false to create a disabled job. |
test | Preview the next 5 fire times of a schedule. |
logs | Tail the newest run log of a job — see what a failed run printed. |
export | Print crontab lines so jobs also run while pi is closed (headless pi -p --no-session, logs under <agentDir>/cron/logs/). |
Example: "every weekday at 9, check CI status and summarize failures" → the
agent converts that to cron add schedule:"0 9 * * 1-5" prompt:"...", verifies
with test, and adds it.
Execution model: a 30s in-process timer fires due jobs as follow-up turns
in the open session; past-due jobs catch up once on the next tick (if pi was
closed at the scheduled time). Jobs only run while a pi process is open — use
export + system crontab for unattended schedules.
Model & thinking pins (Hermes-style): set model:"provider/id" and/or
thinking:"high" on a job and it runs headless in its own pi process
(pi -p --no-session --model … --thinking …) instead of the live session —
useful for cheap/fast models or isolated runs. Output is logged under
<agentDir>/cron/logs/ (default 10 min, configurable via cron.timeoutMs) and the result is delivered
back into the session as a follow-up. export includes the pins in crontab
lines. Headless children run with PI_CRON_DISABLED=1: the cron scheduler is
off inside them (no parent/child races on jobs.json) and job mutations
(add/remove/run/enable/disable) are refused — a fired run can never
schedule more jobs.
Loop guard: for 30s after a fire is armed, add/remove/run/enable/disable
are refused. This is a time window, not in-flight immunity — a fired turn running
longer than 30s can still mutate. Treat fired prompts as trusted inputs, same as
any tool call the session makes.
Working directory: unpinned jobs only deliver into a session whose cwd matches the
job's recorded cwd. A session opened elsewhere skips the fire and marks it
[FAIL: cwd mismatch …] (visible in cron list / logs) instead of running the
prompt against the wrong project. For cross-cwd reliability, pin
model/thinking — pinned jobs run headless in job.cwd no matter which
session ticks first.
Single session per agent dir: the jobs store has no cross-process lock.
Running multiple pi sessions that share an agent dir can double-fire jobs or
lose concurrent edits — use one cron-active session per agent dir, or give
each session its own PI_CODING_AGENT_DIR.
Configuration
settings.json:
{ "cron": { "enabled": true, "tickMs": 30000, "timeoutMs": 10800000 } }
enabled— global kill switch for the scheduler.tickMs— tick interval (clamped 5s–10min).timeoutMs— hard cap for headless (pinned) child runs — SIGTERM at the cap, SIGKILL after a 5s grace (clamped 1min–24h, default 10min). Raise it for long pinned jobs.
Notes
- Every fired job spends model tokens on a real turn — keep prompts short.
- Schedule validation and fire-time math use
cron-parser. - Headless cron children run with
HERDR_ENVstripped (andPI_CRON_DISABLED=1), so they never auto-delegate to herdr panes — subagents in cron jobs always run in-process.