docsconceptsscheduling & triggers

Scheduling and triggers

A Cast agent isn't limited to acting when you talk to it. It can wake on a schedule, react to an inbox or calendar, or be poked by its own code.

Wake on the clock

The simplest way to wake a Cast agent is writing a schedule into its blueprint. The agent wakes at the appointed time, reads its own message, and acts on it. Reach for this when you know the rhythm up front: a morning briefing, a nightly reflection, a weekly plan.

📖 JARGON
The schedule lives in blueprint/props/schedule.txt. One line per scheduled message — standard 5-field cron with an optional TZ= prefix, then the channel, then the message text. Hot-reloaded; edits land on the next message. See Authoring blueprints for the full grammar.
# Daily briefing on weekdays
0 7 * * 1-5    default     Send the morning briefing.

# Nightly reflection
0 22 * * *     reflection  Look back over the day.

# Sunday-evening planning
0 21 * * 0     default     Plan the week ahead.

Wake on the agent's initiative

The author can't anticipate every future fire. The agent sets the schedule itself mid-conversation. You mention a deadline. The agent calls a tool, and the turn fires later. The cadence belongs to the agent, set by what you just said rather than written into the blueprint.

📖 JARGON
The agent calls task__schedule — one-shot or recurring, tied to a channel. The task persists in state/tasks.json and survives restart. Companion tools (task__list, task__pause, task__cancel) let the agent manage what it has set.
agent
This refactor should only take a weekend.
Noted. I'll check back in two weeks.
2 weeks later
Two weeks ago you thought the refactor would take a weekend. How's it going?

Wake on triggers

An email arrives, the calendar fires a reminder — and your agent reacts. Cast ships with extensions that watch your inbox and calendar. When the extension sees what it's watching for, it wakes the agent.

📖 JARGON
Extensions are typed packages installed on the server. An agent opts in through its capabilities config; the extension handles the watching, the auth, the parsing. See Capabilities for what's bundled.
agent
Calendar reminder
Your retro starts in 10 minutes. Want me to pull the issues you opened this sprint?
yes please

Wake on your own code

For the use cases that aren't covered by extensions — a webhook, a private API, etc. — the agent can run its own code on the side. The code runs outside the sandbox, decides when to act, and pings the agent through the same delivery path.

📖 JARGON
Service code lives at blueprint/service/ and runs as a child process the framework supervises. See Writing services for the trust model and the IPC contract.
  • Capabilities — extensions and services in depth, including their trust and isolation properties.
  • Channels — every trigger lands on a channel; the channel's config shapes the turn the agent receives.
  • Conversation grid — when people share one agent, each gets their own cell; a shared file lets those cells coordinate.