> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mesh.texturehq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Schedules

> Set up reminders and recurring read-only work with durable occurrence history.

Schedules let an agent deliver a reminder or a read-only briefing at a future
time or on a recurring cadence. Each firing has its own bounded run and recorded
outcome. Use a [commitment](/runtime/commitments) when the agent should keep
working toward one verified outcome across turns.

A schedule delivers through the agent's existing connector to the conversation
or thread where it was requested. Scheduled runs can read information and send
that delivery; they cannot make other external writes, run workspace commands,
write memory, or create more schedules or commitments.

## Create and manage a schedule

Ask the agent in the conversation where you want the result, for example:

> Every weekday at 9 AM America/New\_York, summarize the open issues here.

Include the instruction, cadence, and named timezone. The agent uses
`create_schedule` and confirms only after the schedule is saved. Ask it to list,
edit, pause, resume, cancel, or run the schedule now using `list_schedules` and
`manage_schedule`.

Only the original requester can manage a schedule through conversation.
Authorized operators can inspect history and pause, resume, cancel, or request
an immediate run on the agent's **Schedules** page (`/agents/{slug}/schedules`).
The saved destination cannot be changed to a different audience.

## Supported times

| Cadence | Supported form |
| - | - |
| Daily | A local `HH:MM` time in an IANA timezone. |
| Weekly | A local time and one or more weekdays; Sunday is 0, Saturday is 6. |
| Interval | Every 15–525,600 minutes, measured from the scheduled instant. |
| Once | One RFC3339 instant, including a UTC offset. |

Every cadence requires an explicit IANA timezone, such as `America/New_York` or
`UTC`. Arbitrary cron expressions and monthly rules are not supported.

For daylight-saving changes, a local time that does not exist is skipped. A time
that occurs twice runs once, at its earlier occurrence. Interval schedules do
not drift based on how long the previous execution took.

This is the tool request for a weekday briefing:

```json theme={null}
{
  "instruction": "Summarize the open issues in this thread.",
  "cadence": {
    "kind": "weekly",
    "timezone": "America/New_York",
    "time": "09:00",
    "weekdays": [1, 2, 3, 4, 5]
  }
}
```

Fields that do not apply to the cadence can be omitted or set to `null`.
Conflicting cadence fields are rejected. Management actions other than `update`
can omit `request`; only `run_now` needs a `request_id` UUID for idempotency.

## Execution and missed runs

Schedules require PostgreSQL and `MESH_RUN_WORKER_ENABLED=true`. The worker must
receive CPU between HTTP requests. The scheduler checks every ten seconds;
scheduled times indicate when a run becomes eligible, rather than a guaranteed
delivery instant.

Each occurrence uses the primary model, at most four model iterations, and a
five-minute deadline. Only replayable query tools are offered. Idle scheduler
checks do not call a model. Human conversation work takes priority.

Only one occurrence of a schedule can be active. When a regular firing overlaps
an active occurrence, it is recorded as skipped. After downtime, Mesh coalesces
missed firings into the latest occurrence within a one-hour catch-up window and
records skipped history. A busy conversation can defer pickup within that window.

**Run now** preserves the regular cadence. Its request is durable, including when
the requesting conversation turn is still active, and its idempotency key survives
retries and restarts. Edits, pause, or cancellation invalidate pending manual
requests. Edits are refused while an occurrence is running.

Pausing or cancelling fences further work but cannot retract a delivery already
in flight. An uncertain delivery appears in occurrence history instead of being
blindly resent. Every execution rechecks the agent, schedule, source audience,
and evidence permissions.

## Limits and monitoring

An agent can retain up to 100 active or paused schedules. Across enabled agents,
at most 16 occurrences can await completion installation-wide, with at most four
per agent and the shared run-worker admission limits. Disabled agents do not
occupy another agent's scheduled-work capacity.

The Schedules page shows next and last execution, occurrence outcomes, delivery
uncertainty, and attributed control history. Operators can monitor
`GET /api/schedules/health` with a read-only API token or use the repository's
`scripts/check-schedules.sh`. Health checks cover stale scheduler heartbeats,
overdue scheduled/manual requests, and queued occurrences that have not settled.
An independent monitor is needed to detect a total Mesh outage.

See the [operator API](/operator-api#schedules) for the control and history
endpoints. Implementation and calendar tests live in `internal/schedule`;
worker-to-connector integration tests live in
`internal/app/schedules_integration_test.go`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.