cron vs hooks for recurring agent work

TL;DR

Use cron for work that happens on a clock (daily briefings, weekly reports, periodic sweeps) and hooks for work that happens on an event (a new message, a file change, an API callback). Time-based needs go to the scheduler; reaction-based needs go to the event system. When in doubt, cron is simpler to reason about and hooks are cheaper to run; pick by asking "does this start with a time or with a thing happening".

cron vs hooks for recurring agent work

Use this when

• You are designing automation that runs unattended
• You have a cron job polling for something that is really an event
• You have hooks firing on a schedule-shaped problem
• You are choosing the mechanism for a new recurring task
• You need to explain the choice to a teammate

Not for this skill when

• You need cron expression syntax (reference docs cover that)
• You are implementing a specific webhook receiver (implementation skill)
• The work is one-off, not recurring (just run it)
• You are choosing between polling intervals (that is a cron tuning question)

Steps

1. Classify the trigger: time or event. "Every morning at 7" is time; "when a new thread appears" is event; "check every 10 minutes whether anything changed" is a time-shaped workaround for a missing event. Be honest about which one it really is.

   trigger: [time: schedule | event: what happens]

   Expected output: a classification. Success check: you can state it in one clause without "and also".

2. Default time-triggers to cron. Cron is inspectable (one list shows everything scheduled), debuggable (logs per run), and survivable (the scheduler outlives your session). Anything with "daily", "weekly", or "every N minutes" belongs here.

   [ ] job listed in the scheduler with its schedule visible
   [ ] each run logs to a known location

   Expected output: the job in cron. Success check: you can answer "when does it run next" without reading code.

3. Default event-triggers to hooks. Hooks fire once per event with the event's context attached, which beats polling on latency, cost, and log noise. If the event source offers webhooks or file watchers, use them instead of a 5-minute poll loop.

   [ ] event source identified (message bus, file watcher, webhook)
   [ ] hook receives the event payload directly

   Expected output: the hook wired to the event. Success check: median reaction time beats any reasonable poll interval.

4. Handle the hybrids explicitly. "Every morning, process everything that arrived overnight" is cron with an event-flavored batch; "on this event, but at most once per hour" is a hook with a time-shaped guard. Name the hybrid and put the guard where it belongs.

   hybrid: [cron batch over events | hook with rate guard]
   guard: [where the limit lives]

   Expected output: a named pattern with its guard. Success check: the failure mode (missed batch, doubled firing) is written down.

5. Give every scheduled thing an owner, a stop condition, and logs. Unowned crons accumulate until nobody knows what runs; every job gets a name, a purpose line, and a condition under which it gets deleted.

   owner: [name], purpose: [one line], delete when: [condition]

   Expected output: metadata on every job and hook. Success check: a quarterly review can kill any job from its metadata alone.

Variant phrasings

Should I use cron or a webhook for this

Choice phrasing. Step 1: time-shaped need goes to cron, event-shaped need goes to the hook.

Polling vs event-driven for agents

Architecture phrasing. Polling is cron-shaped; events are hook-shaped; step 3 explains why hooks win when real events exist.

Recurring agent tasks best practices

Practice phrasing. Steps 2, 4, and 5: cron by default, hybrids named, everything owned and logged.

Cron job not running, how to debug

Troubleshooting phrasing. Check the scheduler list, then the run logs, then the stop conditions in step 5; silent crons are usually deleted-by-cleanup or environment drift.

Why it happens

Time and events are different shapes of "when", and each mechanism is optimized for one shape. Cron treats every run as independent, which is perfect for reports and sweeps and terrible for "react to this new thing". Hooks carry event context, which is perfect for reactions and meaningless for "every Tuesday". Mismatches produce polling loops (cron doing a hook's job, expensively) or missed schedules (hooks doing cron's job, unreliably).

Edge cases / pitfalls

• Cron environments are minimal. PATH, env vars, and working directory differ from your shell; every cron job should set what it needs explicitly or it will fail at 3am in ways it never fails at 3pm.
• Hooks need idempotency more than cron does. Events can redeliver; a hook that is not safe to run twice will double-process eventually.
• Do not chain crons by timing ("job B runs 5 minutes after job A"). Chains break on slow runs; make B check A's output or merge them.
• A hook with no dead-letter handling loses events silently. Log every firing and alert on the error path, not just the happy path.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstoivxsJRj0aWKh3GrpAguQ