Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

3.2 KB
Raw Blame
---
id: scheduling
title: Scheduling
---

Mercury can schedule tasks using cron expressions or one-shot delays.

## Recurring tasks

Tell Mercury in conversation:

- "Remind me every day at 9am to check the server"
- "Schedule a weekly summary every Monday at 10am"

## One-shot delays

- "Remind me in 15 minutes to take a break"
- "Ping me in 2 hours about the deployment"

Tasks persist to `~/.mercury/schedules.yaml` and restore on restart. Responses route back to the channel (CLI or Telegram) where the task was created.
## Time zones and overlap

Use a timezone for recurring work, for example: “Every weekday at 9am in
America/New_York, brief me on my calendar.” The `schedule_task` tool accepts an
IANA `timezone`; the Schedules editor exposes the same setting. Existing schedules
without one continue using the host timezone. Cron follows that zone's local clock,
including daylight-saving changes.

A schedule never queues another main-agent run while its previous run is still
queued or running. Overlapping ticks are skipped, rather than accumulated for later.
Recurring ticks missed while Mercury was offline are not replayed.

## Offline and interrupted work

One-shot tasks have an explicit `missed_run_policy`:

- `skip` (default, including older schedules): keep a skipped record when Mercury
  starts after the due time.
- `run_once`: start the overdue task once after restart, provided no run had begun.

This policy does **not** retry failed or interrupted work. Mercury records a run
before invoking it. If the process stops before the outcome is confirmed, the run
becomes **interrupted** and the schedule pauses. Failed runs also pause, because an
external action may have succeeded before its response was lost.

Check the prior run's effects before repeating it. In **Schedules → Edit**, choose
**Schedule again** to explicitly resume. For a one-shot, the delay starts again
from when you save. Editing only a description or policy does not repeat the work.
The API equivalent is `PUT /api/schedules/:id` with `{"resume": true}` and, for a
one-shot, the desired `delaySeconds`. Running tasks cannot be edited.

## Run outcomes

The Schedules page and `list_scheduled_tasks` show pending, running, completed,
failed, interrupted, skipped, or dispatched status. **Completed** means the main
agent finished its turn; inspect its response for the actual task result. Bot
schedules show **dispatched** after their separate queue accepts them; inspect the
bot's run history for completion. Scheduled bot jobs whose run or retry was
interrupted go to the dead-letter queue (DLQ) instead of replaying automatically;
future routines pause. Check their effects, then use `/bots start <id>` to resume
future routines or `/bots replay <id> <jobId>` to explicitly repeat that job.
A fresh queued bot job that never started can still resume. Manual/chat bot jobs
keep their existing recovery behavior.

Run records are stored with the schedule in `~/.mercury/schedules.yaml`, using an
atomic replacement. The latest run is kept for each recurring task. The most recent
100 resolved one-shot records are retained; active work and unresolved failures are
kept until you remove them. These safeguards prevent automatic scheduler replay;
they cannot guarantee exactly-once behavior from external services.