Cron syntax reference

InsightWorker schedules use standard 5-field cron expressions, parsed by cron-parser.

Format

┌─── minute (0–59)
│ ┌─── hour (0–23)
│ │ ┌─── day of month (1–31)
│ │ │ ┌─── month (1–12 or JAN–DEC)
│ │ │ │ ┌─── day of week (0–6, Sun–Sat, or SUN–SAT)
│ │ │ │ │
* * * * *

Common patterns

Expression	Meaning
`0 9 * * *`	Every day at 09:00
`/15 * * *`	Every 15 minutes
`0 9 * * MON-FRI`	Weekdays at 09:00
`0 8 * * 1-5`	Same as above (numeric weekdays)
`0 9,17 * * *`	09:00 and 17:00 every day
`0 9 1 * *`	First of every month at 09:00
`0 0 1 1 *`	Once a year at midnight Jan 1
`30 * * * *`	Every hour at :30
`0 9-17 * * MON-FRI`	Every hour 09:00-17:00 weekdays
`/5 9-17 * MON-FRI`	Every 5 min during business hours

Operators

Operator	Meaning	Example
`*`	any value	`* * * * *` = every minute
`,`	list	`1,15,30 * * * *` = at :01, :15, :30 of every hour
`-`	range	`9-17` = 9 through 17
`/`	step	`*/15` = every 15 (units of the field)

Time zones

Schedules respect the system time zone of the machine running the daemon. To override per-schedule, set:

# ~/.insightworker/schedules.yaml
schedules:
  - name: morning-digest
    cron: "0 9 * * MON-FRI"
    timezone: America/New_York   # IANA tz database name
    skill: pm-agent-sprint-digest

If the daemon machine and your team are in different time zones, always set timezone explicitly — relying on system tz is a debugging hazard.

Verifying

Always dry-run a new schedule before relying on it:

insightworker schedule dry-run morning-digest
# Output:
#   Next 5 fires:
#     2026-05-04 09:00:00 EDT
#     2026-05-05 09:00:00 EDT
#     2026-05-06 09:00:00 EDT
#     2026-05-07 09:00:00 EDT
#     2026-05-08 09:00:00 EDT

If "Next 5 fires" looks wrong, fix the cron expression before enabling.

Common pitfalls

Pitfall	Example	Fix
Day-of-week 7 vs 0 for Sunday	`0 9 * * 7`	Use 0 or `SUN` for portability
Step on a non-uniform field	`0 0 /5 *` doesn't fire every 5 days reliably	Avoid `/` on day-of-month; use a runtime check inside the skill
12am vs 12pm confusion	`0 12 * * *`	Cron is 24h: 0=midnight, 12=noon
Both day-of-month and day-of-week set	`0 9 1 * MON` fires on the 1st OR Monday	Use one or the other; don't combine unless you mean OR
TZ not set, daemon on UTC server	Schedule fires 4-8h "early"	Set `timezone:` per schedule