Cron Jobs

Schedule recurring agent tasks. Define jobs in config/cron.yaml or manage them via the CLI.

Quick example

# Send a morning brief to Telegram every day at 8 AM
vesper cron add morning-brief \
  --schedule "0 8 * * *" \
  --agent auto \
  --prompt "Good morning, give me the brief for {{date}}" \
  --deliver-to "telegram:@me"

Cron expression syntax

Standard 5-field crontab: minute hour day-of-month month day-of-week

Field	Range	Special
minute	0-59	* */N
hour	0-23	* */N
day-of-month	1-31	* */N
month	1-12 or JAN-DEC	*
day-of-week	0-6 or SUN-SAT	*

Shortcuts

@hourly → 0 * * * *
@daily → 0 0 * * *
@weekly → 0 0 * * SUN
@monthly → 0 0 1 * *
@yearly → 0 0 1 1 *

Prompt templates

Prompts support template variables interpolated at run time:

Variable	Value
`{{now}}`	ISO timestamp
`{{date}}`	YYYY-MM-DD
`{{yesterday}}`	Previous day (YYYY-MM-DD)
`{{time}}`	HH:MM
`{{weekday}}`	Monday / Tuesday / ...
`{{user}}`	Current OS user

Delivery targets

Set deliver_to to send the agent's output somewhere:

telegram:@username — Telegram DM
slack:#channel — Slack channel
discord:#channel — Discord channel
email:user@example.com — Email
log — append to ~/.openvesper/logs/cron.log
console — stdout (useful for debugging)
none — discard output

YAML config

Define jobs declaratively in config/cron.yaml:

jobs:
  - id: morning-briefing
    name: Daily morning briefing
    schedule: "0 8 * * *"
    agent: auto
    prompt: |
      Good morning. It is {{date}}. Give me:
      - Top crypto moves overnight
      - Calendar today
      - Weather
    deliver_to: "telegram:@me"
    enabled: false

  - id: friday-retro
    name: Friday weekly retro
    schedule: "0 17 * * FRI"
    agent: productivity-coach
    prompt: "Run my weekly retro for week of {{date}}"
    deliver_to: "telegram:@me"
    enabled: false

CLI commands

# List all jobs
vesper cron list

# Show summary stats
vesper cron status

# Add a job
vesper cron add daily-brief \
  --schedule "0 8 * * *" \
  --agent auto \
  --prompt "Give me my daily brief for {{date}}"

# Run a job immediately (bypass schedule)
vesper cron run daily-brief

# Enable/disable
vesper cron toggle daily-brief

# Remove
vesper cron remove daily-brief

Heartbeats — per-agent autonomous mode

Each agent in .agents/<name>/ has a HEARTBEAT.md with frontmatter:

---
schedule: "0 9 * * MON"
enabled: false
---

# Heartbeat — code-reviewer

## Recurring task

Weekly: list open PRs older than 3 days. Suggest which to prioritize.

To activate a heartbeat:

Set enabled: true in the frontmatter
Run vesper daemon start

The daemon reads all .agents/*/HEARTBEAT.md on startup and schedules each enabled one.

Running the scheduler

The scheduler runs inside the gateway daemon:

# Start the daemon (auto-loads cron.yaml + HEARTBEAT.md files)
vesper daemon start

# Check status
vesper daemon status

# Stop
vesper daemon stop

Without the daemon running, jobs do not fire on schedule. CLI commands like vesper cron run work without the daemon by triggering immediate execution.

State persistence

Job state (last run, run count, errors, next run) is stored at:

~/.openvesper/workspace/heartbeat.json

File permissions are set to 0600 on POSIX systems.

Privacy

All scheduling, execution, and state lives on your local machine. Cron output is never sent to OpenVesper servers — only to the deliver_to target you configure. See Security for full details.