Scheduled Tasks
Create recurring and one-shot tasks with natural language or cron expressions. The agent executes the task prompt on schedule.
Tool Name
scheduler
Actions
| Action | Required Params | Description |
|---|---|---|
create | name, schedule, prompt | Create a new scheduled task |
list | — | List all tasks with status and next run time |
delete | id | Delete a task by UUID |
pause | id | Pause a task (stops firing) |
resume | id | Resume a paused task (recomputes next run) |
Create Parameters
| Key | Type | Default | Description |
|---|---|---|---|
name | string | — | Human-readable label for the task |
schedule | string | — | Natural language or 5-field cron expression |
prompt | string | — | What the agent should do when the task fires |
oneshot | bool | false | Fire once then auto-delete |
trusted | bool | false | Run with full autonomy (no terminal approval needed) |
Natural Language Schedules
The scheduler parses common patterns into cron expressions:
| Input | Cron | Description |
|---|---|---|
hourly | 0 * * * * | Every hour at :00 |
daily | 0 0 * * * | Every day at midnight |
weekly | 0 0 * * 0 | Every Sunday at midnight |
monthly | 0 0 1 * * | First of the month |
every 5m | */5 * * * * | Every 5 minutes |
every 2h | 0 */2 * * * | Every 2 hours |
daily at 9am | 0 9 * * * | Every day at 9:00 AM |
daily at 14:30 | 30 14 * * * | Every day at 2:30 PM |
weekdays at 8:30 | 30 8 * * 1-5 | Mon-Fri at 8:30 AM |
weekends at 10am | 0 10 * * 0,6 | Sat-Sun at 10:00 AM |
in 2h | (computed absolute) | One-shot, fires once in 2 hours |
in 30m | (computed absolute) | One-shot, fires once in 30 minutes |
Standard 5-field cron expressions are also accepted directly (e.g., 0 9 * * 1-5).
Configuration
config.toml
[scheduler]
enabled = true
tick_interval_secs = 30
[[scheduler.tasks]]
name = "Morning check-in"
schedule = "weekdays at 9am"
prompt = "Check system health and report any issues"
trusted = true
[[scheduler.tasks]]
name = "Backup reminder"
schedule = "weekly"
prompt = "Remind me to run backups"Task Storage
Tasks are persisted in SQLite (scheduled_tasks table). Config-defined tasks are synced on startup — removed tasks are cleaned up automatically. Tasks created via the tool persist indefinitely.
Missed Tasks
On startup, the scheduler checks for tasks that should have fired while the daemon was down. Missed tasks are fired immediately during recovery.
Trusted vs Untrusted
Trusted tasks run with full terminal access (no approval needed). Untrusted tasks (default) require approval for any terminal commands, just like email trigger sessions.