Scheduling

A headless agent needs to be started by something. That something is a scheduler (time-based) or a trigger (event-based). Picking the right one is architecture.

Time-based scheduling

Cron (traditional)

Old reliable. A crontab entry on a server that runs your agent script at specified intervals.

# Every weekday at 9am: generate daily report
0 9 * * 1-5 /usr/local/bin/claude-daily-report.sh

Pros: simple, free, everywhere. Cons: single-node; no retry on failure; hard to monitor.

Claude Code's /loop and /schedule

Built-in skills for recurring work. /loop 5m /my-skill runs a skill every 5 minutes; /schedule sets up remote triggers.

Cloud scheduler

Google Cloud Scheduler, AWS EventBridge, Cloudflare Cron. Managed. Better monitoring and retry than cron.

Event-based triggers

Webhooks

Service X emits an event (new email, new issue, new customer); your endpoint catches it and triggers an agent.

Polling-to-event

If the service doesn't emit webhooks, poll it on a schedule, detect changes, fire the agent only on new data.

Message queues

For high-volume or multi-tenant agent work: Redis streams, SQS, RabbitMQ. Agent workers consume from the queue.

Choosing the right cadence

• Seconds, use event triggers, not polling. Polling this fast is expensive.
• Minutes, polling OK if the source is cheap; webhooks better.
• Hourly / daily, cron or cloud scheduler. Straightforward.
• Weekly / monthly, scheduled, probably overkill to script unless the task is large.

Designing for scheduled runs

• Idempotency. If the job runs twice (it will), it shouldn't cause problems. Use a "last-run" marker so the agent skips work it's already done.
• Bounded time. Every run should have a deadline. Set --max-turns; set a wall-clock timeout at the shell level.
• Graceful degradation. If a dependency is down (API outage), the agent should log and skip, not fail loudly and require manual intervention.
• Status reporting. Every run reports success/failure somewhere, a log file, a Slack channel, a dashboard.

Overlap handling

What if run N is still going when run N+1 is scheduled? Three options:

• Skip. Don't start N+1 if N is still running. Safest default.
• Queue. Wait for N, then start N+1. Good for queue-based work.
• Parallel. Start N+1 regardless. Only if the tasks are truly independent.

Observability

Scheduled agents are background agents. You don't see them. You need instruments.

• Heartbeats. Every successful run pings a dead-man's-switch (Healthchecks.io, BetterUptime). If the ping doesn't arrive, you get alerted.
• Cost tracking. Tag every API call with the agent name; bill alerts.
• Output auditing. Save every run's output somewhere queryable.