Scheduling
Schedule agents or teams to perform tasks at specific times or intervals using natural language.
By default, tasks run in the same scope where they were created: the room timeline for room-level schedules, or the current thread for threaded schedules.
The schedule() tool accepts new_thread=True to start a fresh thread per fire: each fire posts a room-level root and the responding agent answers in a new thread under it with a fresh session.
Commands
Schedule a Task
One-Time Tasks:
Recurring Tasks:
!schedule Every hour, @shell check server status
!schedule Daily at 9am, @finance market report
!schedule Weekly on Friday, @analyst prepare weekly summary
Conditional Workflows (polling-based):
Conditional or event-like requests are converted to recurring cron-based polling schedules.
For predictable behavior, include an explicit polling cadence.
The condition is embedded in the task message so the scheduled responder checks it on each poll cycle.
These are not real event subscriptions — they are periodic checks.
!schedule Every 5 minutes, check if I got an email about "urgent"; if so, @phone_agent call me
!schedule Every 10 minutes, check whether Bitcoin dropped below $40k; if so, @crypto_agent notify me
Edit a Schedule
Edits an existing scheduled task by ID.
The task description is re-parsed to update timing and content.
List and Cancel Schedules
!list_schedules # Show pending tasks
!cancel_schedule <task-id> # Cancel specific task
!cancel_schedule all # Cancel all tasks in room
Aliases: !listschedules, !list-schedules, !list_schedule, !listschedule, !list-schedule, !inspect_schedules, !inspectschedules, !inspect-schedules, !inspect_schedule, !inspectschedule, !inspect-schedule, !cancelschedule, !cancel-schedule, !editschedule, !edit-schedule
Use !help schedule for detailed inline help on scheduling commands.
Agent and Team Mentions
Include @agent_name or @team_name in your schedule to have specific responders answer.
The scheduler validates that mentioned agents and teams are available in the room before creating the task.
History Limits
Scheduled tasks normally use the responder's configured conversation history policy.
Add a context phrase when you want each run to see less of the current room or thread.
Use with no history, without context, or context-free when the scheduled responder should see no prior room or thread messages; the system prompt and fired task message remain available.
Use phrases such as with only the last 5 messages of context or include the last 5 messages to cap each scheduled run to recent context.
!schedule Every hour, @ops check deployment health with no history
!schedule Daily at 9am, @research summarize AI news with only the last 5 messages
For edits, omitted fields stay unchanged, including any existing history limit.
Use restore full history or use unlimited history in an edit to remove a history limit.
!edit_schedule task42 keep the same schedule but restore full history
!edit_schedule task42 every weekday at 8am check build status with no history
Timezone
Schedules use the timezone from config.yaml (defaults to UTC):
Limitations
- Schedule type cannot be changed — editing a one-time task to be recurring (or vice versa) is not supported.
Cancel the existing task and create a new one instead.
- Conditional workflows are polling — event-like schedules (If ..., When ...) are converted to recurring cron polls, not real event subscriptions.
Persistence
Schedules are stored in Matrix room state and persist across restarts.
New schedules use the live runtime to start their in-memory runners immediately.
Edits are state-only Matrix writes.
Running tasks pick up edited state on their next poll instead of relying on caller-supplied cache or restart hooks.
Past one-time tasks within the recovery grace window are queued and started in order after Matrix sync is ready. Older missed one-time tasks are marked failed instead of executing unexpectedly.
Only the router restores persisted schedules after startup — individual agents do not restore their own.
On shutdown, the router cancels its in-memory scheduled tasks before exiting.