What Are Cron Jobs?

Cron jobs are scheduled tasks that run at specific times:

Reminders

Recurring reports

Scheduled checks

Time-based automation

They run independently of your main session.

When to Use Cron

Use Cron For

Exact timing ("9am every Monday")
One-shot reminders ("in 20 minutes")
Independent tasks
Different model/settings than main session

Use Heartbeat Instead For

Batched periodic checks
Tasks needing conversation context
Flexible timing
Combined with other checks

Creating Cron Jobs

Basic Job

cron(action="add", job={
  "text": "Send weekly status report",
  "schedule": "0 9 * * MON",
  "channel": "telegram"
})

One-Time Reminder

cron(action="add", job={
  "text": "Reminder: Meeting in 15 minutes",
  "runAt": "2025-02-01T15:00:00Z"
})

Cron Schedule Syntax

Standard cron format:

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, 0=Sunday)
│ │ │ │ │
* * * * *

Examples

0 9 * * *       # 9am every day
0 9 * * MON     # 9am every Monday
0 */2 * * *     # Every 2 hours
30 14 1 * *     # 2:30pm on 1st of month
0 9 * * MON-FRI # 9am weekdays

Managing Jobs

List Jobs

cron(action="list")

Remove Job

cron(action="remove", jobId="job-id-here")

Update Job

cron(action="update", jobId="job-id-here", patch={
  "schedule": "0 10 * * *"
})

Run Immediately

cron(action="run", jobId="job-id-here")

Job Configuration

Full Options

{
  "text": "Task description/prompt",
  "schedule": "0 9 * * *",     // Cron expression
  "runAt": "2025-02-01T10:00:00Z",  // Or specific time
  "channel": "telegram",        // Where to deliver
  "model": "claude-sonnet",     // Optional model override
  "thinking": "high",           // Optional reasoning level
  "enabled": true               // Can disable without deleting
}

Common Patterns

Daily Reminder

{
  "text": "Good morning! Here's your daily briefing...",
  "schedule": "0 8 * * *"
}

Weekly Report

{
  "text": "Generate and send the weekly project status report",
  "schedule": "0 9 * * FRI"
}

Follow-Up Reminder

{
  "text": "Reminder: Follow up on the proposal you sent Tuesday",
  "runAt": "2025-02-03T10:00:00Z"
}

Recurring Check

{
  "text": "Check API status and alert if any issues",
  "schedule": "0 * * * *"  // Every hour
}

Writing Good Job Text

For Reminders

Include context:

"Reminder: You have a 1:1 with Sarah about the Q1 goals.
Meeting link: [link]
Prep notes: Review the goal doc first."

For Tasks

Be specific:

"Run the weekly backup:
1. Backup database
2. Verify backup integrity
3. Report status to channel"

With Recent Context

Use contextMessages for conversation context:

cron(action="add", job={...}, contextMessages=3)

Error Handling

Job Failures

If a job fails:

Error is logged

Job continues on schedule (for recurring)

Check logs for details

Monitoring Jobs

Check job runs:

cron(action="runs", jobId="job-id")

Best Practices

Set Timezone

Be aware of timezone:

Server may be UTC

Specify times accordingly

Document timezone assumptions

Don't Over-Schedule

Too many cron jobs:

Costs tokens

Creates noise

Reduces value

Use Descriptive Text

Future you needs to understand:

✅ "Weekly marketing report for stakeholders"
❌ "Do the thing"

Clean Up Old Jobs

Remove completed one-time reminders.

Test First

Run job manually to verify:

cron(action="run", jobId="job-id")

Cron vs Other Options

Need

Use

Exact time, one task	Cron
Multiple periodic checks	Heartbeat
Event-driven	Webhooks
User-requested delay	setTimeout in session

Conclusion

Cron jobs enable time-based automation:

Reminders

Scheduled reports

Recurring tasks

Precise timing

Use them for specific timing needs, heartbeats for general periodic work.

Next: Browser Automation - Web interaction for agents