Scheduled prompts

A scheduled prompt hands one or more agents the same text at set times: once, or every interval from a start time. Each prompt has a name, its title. The swarm keeps every prompt, and each agent it names fires it in its own container, so a fire needs neither the hive nor the swarm controller to be up at that moment, only the agent.

Operators manage them with swarmctl schedule on the swarm controller's host. Agents can't create, change or remove one. For a one-off wake an agent sets itself, it uses remind, which stays inside its container.

Managing them

# swarmctl schedule add --name standup --agent scribe --agent iris \
    --body "post the standup summary" --at 2026-10-05T09:00:00+02:00 --every 1d
added schedule kqzpmwab
kqzpmwab  "standup"  every 1d  from 2026-10-05T07:00:00Z  next 2026-10-05T07:00:00Z  agents: iris, scribe  | post the standup summary

# swarmctl schedule list
# swarmctl schedule list --agent scribe
# swarmctl schedule edit kqzpmwab --body "post the standup summary to the team room"
# swarmctl schedule edit kqzpmwab --add-agent atlas --remove-agent iris
# swarmctl schedule pause kqzpmwab
# swarmctl schedule resume kqzpmwab
# swarmctl schedule rm kqzpmwab

• --agent names an agent to fire the prompt in; repeat it for more. Each must be an agent some hive's wanted state declares.
• --at takes an RFC 3339 time with its offset, or unix seconds. Without it the first fire is now. A time in the past fires its latest past time once, as soon as each agent reads the prompt.
• --every takes a count and a unit, s, m, h or d. Without it the prompt fires once.
• schedule edit changes only the flags you pass and keeps the id. --once turns a recurring prompt into a one-shot. --add-agent and --remove-agent change who gets it; removing the last agent fails, so remove the prompt instead.
• schedule list shows one row per prompt: id, name, cadence, start, next fire time, agents, and the first line of the body.

The full flag reference is swarmctl-cli.md.

When a prompt fires

A prompt's fire times are its start time plus whole intervals. Each agent works them out from the prompt itself, so:

• Editing the text or the name doesn't move them. Neither does changing the agents. Only a new --at or --every does.
• An agent that was down or disconnected fires once. When it's back, it fires the latest time it missed and then carries on at the next one. The earlier missed times don't fire.
• A restart refires nothing. Each agent records the last time it fired for each prompt in its state database, and fires a time only when it's later than that. An agent removed from a prompt and added back keeps that record, so it doesn't refire a time it already fired.
• A one-shot fires once, even though it stays in schedule list until you remove it. Moving its --at to a later time fires it again then.
• A paused prompt doesn't fire, and the times that pass while it's paused don't fire when it resumes. An agent marks those times as passed while it watches the paused prompt; if the agent was down for the whole pause, it fires the latest time it missed once, as above.

A fire reaches the agent as a schedule loose end with the prompt's text. The agent's turn loop wakes for it like any other loose end. If the agent hasn't dealt with the previous fire yet, the new fire replaces it rather than adding a second one; once the agent dismissed the previous one, the next fire opens a new one.

Each agent reads its prompts every 10 seconds, so a fire can land up to 10 seconds after its time. A change reaches each agent within the same window, or within a minute if the controller's first attempt to pass it on failed.

When a prompt doesn't fire

• The agent isn't connected to the swarm queue. It reads its prompts with its own swarm-queue credential. A harness that can't connect retries for about five minutes, then exits and comes back; it reads no prompts until a connect succeeds. See Giving the agents the queue too.
• The agent hasn't read its prompts since it started. It fires from the last list it read; until the first read succeeds it fires nothing. A read that fails later keeps the previous list.

{
  "schedules": [
    {
      "id": "kqzpmwab",
      "body": "post the standup summary",
      "anchor_unix": 1791183600,
      "interval_seconds": 86400,
      "paused": false
    }
  ]
}