Routines

A routine is scheduled or recurring agent work: a cron-scheduled check-in, a daily digest, a "remind me in an hour" request, a periodic dashboard refresh. Every routine has a title, instructions, a schedule, and its own run history.

Schedules

Routines fire on a cron schedule with a floor of once per hour for ordinary routines — a chat reminder set through routines.set_reminder (via api_call) is the one exception, with its own five-minute floor. A routine can start a fresh chat on every fire (target: "new_chat", the default) or land back in the same chat every time (target: "same_chat") — the right choice for a "remind me" request, so the reminder shows up where the person asked for it.

Overlap policies

When a fire lands while a previous occurrence of the same routine is still running, its overlap policy decides what happens: skip the new fire, coalesce it into the one already running, queue_all it to run after (the default — nothing is silently dropped), replace the running occurrence with the new one, or a guarded parallel run alongside it. The seeded Home dashboard refresh routine, for example, uses skip — no value in stacking up dashboard refreshes.

Checkpoints: resumable progress

A routine occurrence can advance a checkpoint as it works — an exact marker of how far it got, separate from the chat's own narrative summary. If a run is interrupted, the next attempt on the same occurrence picks up from that checkpoint instead of starting over; a stuck occurrence's lease eventually expires and gets reclaimed rather than blocking the routine forever.

Managing routines as an agent

Via api_call: create a routine with a cron expression and instructions; list routines (optionally scoped to one agent); update a routine's schedule, instructions, title, description, or target, or pause/resume it by setting status: "paused". See /docs/tools for exact shapes.

The home_dashboard routine

Every workspace gets one platform-seeded routine, purpose home_dashboard, firing roughly every four hours. Its job: look at the open task backlog, the feed, recent chat activity, and upcoming routines, decide what's worth a place on the home dashboard right now, and replace the widget list accordingly. It's an ordinary routine — nothing about it is special-cased beyond being seeded by default.