Skip to main content
The cron command manages scheduled tasks that execute agent prompts at specified intervals or cron expressions.

​
Usage

weaver cron <subcommand> [options]

​
Subcommands

​
list

Display all scheduled jobs, including disabled ones. 
weaver cron list
Output: 
Scheduled Jobs:
----------------
  Daily Summary (job-abc123)
    Schedule: every 86400s
    Status: enabled
    Next run: 2026-03-02 09:00
  
  Hourly Check (job-def456)
    Schedule: 0 * * * *
    Status: disabled
    Next run: scheduled

​
add

Create a new scheduled job. 
weaver cron add [options]
​
-n, --name
string
required
Human-readable job name
​
-m, --message
string
required
Message/prompt to send to the agent
​
-e, --every
integer
Run every N seconds (interval-based scheduling)Mutually exclusive with --cronExamples:
  • 300 - Every 5 minutes
  • 3600 - Every hour
  • 86400 - Every day
​
-c, --cron
string
Cron expression (time-based scheduling)Mutually exclusive with --everyFormat: minute hour day month weekdayExamples:
  • 0 9 * * * - Daily at 9:00 AM
  • */15 * * * * - Every 15 minutes
  • 0 0 * * 0 - Weekly on Sunday at midnight
​
-d, --deliver
flag
Deliver agent response to a channelRequires --channel and --to options.
​
--channel
string
Channel to deliver response (telegram, discord, slack)Required when --deliver is set.
​
--to
string
Recipient identifier (chat ID, user ID, channel name)Required when --deliver is set.Format varies by channel:
  • Telegram: Chat ID (e.g., 123456789)
  • Discord: Channel ID (e.g., 987654321)
  • Slack: Channel name (e.g., #general)

​
remove

Delete a scheduled job by ID. 
weaver cron remove <job_id>

​
enable

Enable a disabled job. 
weaver cron enable <job_id>

​
disable

Disable a job without deleting it. 
weaver cron disable <job_id>

​
Job Storage

Jobs are stored at:
  • Location: ~/.weaver/workspace/cron/jobs.json
  • Format: JSON
  • Persistence: Survives gateway restarts
Example jobs.json: 
[
  {
    "id": "job-abc123",
    "name": "Daily Summary",
    "enabled": true,
    "schedule": {
      "kind": "every",
      "every_ms": 86400000
    },
    "prompt": "Summarize today's activity",
    "deliver": true,
    "channel": "telegram",
    "to": "123456789",
    "state": {
      "next_run_at_ms": 1709373600000
    }
  }
]

​
Execution Context

Jobs execute with:
  • Session: Unique per job (maintains conversation history)
  • Tools: Full agent tool access
  • Skills: All loaded skills available
  • Workspace: Restricted to workspace if configured

​
Examples

$ weaver cron add \
  --name "Hourly Backup" \
  --message "Backup workspace to cloud" \
  --every 3600

✓ Added job 'Hourly Backup' (job-xyz789)

​
Cron Expression Reference

FieldValuesSpecial
Minute0-59* / , -
Hour0-23* / , -
Day1-31* / , - ? L W
Month1-12* / , -
Weekday0-6 (Sun-Sat)* / , - ? L #
Common patterns:
  • 0 * * * * - Every hour on the hour
  • */15 * * * * - Every 15 minutes
  • 0 0 * * * - Daily at midnight
  • 0 9-17 * * 1-5 - Every hour, 9 AM-5 PM, weekdays
  • 0 0 1 * * - First day of every month

​
Exit Codes

CodeReason
0Success
1Invalid arguments
1Job not found
1Failed to add/update job

​
Error Handling

​
Missing Required Field

Error: --name is required

​
Missing Schedule

Error: Either --every or --cron must be specified

​
Invalid Cron Expression

Error adding job: invalid cron expression '0 25 * * *'

​
Missing Delivery Config

Error: --channel and --to required when --deliver is set

​
Job Not Found

✗ Job job-xyz789 not found

​
Runtime Behavior

​
Job Execution

Jobs run in the gateway process:
  1. Gateway loads jobs.json on startup
  2. Scheduler calculates next run times
  3. At scheduled time, job executes:
    • Agent processes prompt
    • If deliver: true, sends response to channel
    • Updates next run time

​
Missed Executions

If gateway is down during scheduled time:
  • Interval jobs: Resume on next interval after startup
  • Cron jobs: Skip missed execution, wait for next

​
Delivery Failures

If channel delivery fails:
  • Error logged
  • Job continues scheduling
  • Response not retried

​
Best Practices

Names appear in logs and help identify jobs:
--name "Weekly Database Backup"
Run prompt with weaver agent before scheduling:
weaver agent -m "Generate daily metrics report"
# If output is good, add to cron
Avoid too-frequent jobs that could rate-limit:
  • Minimum recommended: 60 seconds
  • For most tasks: 300+ seconds
Check gateway logs for execution results:
journalctl -u weaver -f | grep cron

Build docs developers (and LLMs) love

Get started for freeTalk to us