Scheduler Tool

Schedule instructions to run at a time or on a recurring interval.

Overview

The scheduler toolset lets an agent make something happen at a chosen time or on a repeating cadence during a session. You give it an instruction and a schedule; when the schedule is due, the instruction is delivered back to the agent, which then carries out the action with its normal tools (shell, api, fetch, and so on).

The scheduler does not run shell or API calls itself. When a schedule fires it injects the instruction into the agent loop via the runtime's recall mechanism — the same primitive background_jobs uses to report completed work — and the agent decides how to act. This keeps every action under the agent's normal tools and permissions rather than adding a second, unattended command runner.

Note

Schedules only fire while the session is running (interactive TUI or a server mode) and are not persisted across restarts. Scheduling requires a host that supports recall; if it does not, create_schedule returns an error.

Configuration

toolsets:
  - type: scheduler

No configuration options.

Tools

create_schedule

Returns the new schedule's id and its next fire time.

cancel_schedule

Schedule specs

The when argument accepts:

Durations use Go's duration syntax (30s, 15m, 2h). Preset and every: intervals are measured from the schedule's creation time (for example hourly fires every hour after it is created), not aligned to wall-clock slots.

Important

Recurring schedules have a one-minute minimum. Every fire injects a message into the agent loop and typically costs an LLM turn, so every: values below 1m are rejected — a typo such as every:1s in place of every:1h would otherwise become a runaway token burn. One-shot schedules (in: / at:) are not restricted, since they fire once.

Example

agents:
  root:
    model: openai/gpt-5-mini
    description: A monitoring assistant
    instruction: |
      Every 15 minutes, run `git fetch` and tell me if origin/main moved.
    toolsets:
      - type: scheduler
      - type: shell

The agent calls:

create_schedule(prompt="Run git fetch and report if origin/main moved", when="every:15m")

Every 15 minutes it is reminded, runs the command with the shell tool, and reports back.

Tip

When to use

Use the scheduler for recurring monitoring, timed one-shots, and unattended housekeeping loops during a long-running session. For work that should run immediately and be awaited, use background_jobs instead.