Routines

A routine is scheduled agent work as a file: a Markdown definition in .claude/routines/ stating what to do, which model to do it with, and on what cadence. A local automation daemon watches the clock and, when a routine is due — or when you trigger one — spawns a fresh headless agent session for that single run. The session reads the definition, does the job, writes its output, and exits.

The concept page explains when a routine is the right tool; the Routines view is where you switch, trigger, edit, and audit them. This page is the depth underneath: the definition format, the cadence model, the reliability machinery, where human approval sits, what it costs, and the shipped catalog.

The definition file

Frontmatter over an instruction body, like every doctrine file:

The body is the instruction set the spawned session executes — usually "act as agent X and produce Y." Because the file is read fresh at each run, improving a routine is just editing it: the next run picks the change up automatically. The in-app editor writes the same file, with a schedule builder and editable config rows, if you prefer never to touch disk.

The cadence model

frequency accepts interval presets (15min, 30min, 1h, 2h, 4h, 12h, 24h), a daily time (daily:09:00), weekly, or a full five-field cron expression for anything irregular. On-demand routines carry no clock at all — they exist to be dispatched from a view or triggered manually with per-dispatch configuration.

Two scheduling behaviors are worth knowing:

• A just-enabled routine proves itself immediately. Enabling a schedule registers the recurring job and a one-shot warmup run about a minute out, so you see a real run — and a real log — right away instead of waiting for the next tick.
• The live switch is app state, not the file. Whether a schedule is on, and at what interval, lives in the daemon's own state; the definition file stays a clean template. Toggling a routine in the view never edits the file, and editing the file never silently arms a schedule.

How a run executes

Each run is a fresh process: the daemon spawns a new headless agent session with the routine's model, feeds it the instruction, and lets it work until done or timeout. No context carries over between runs — every execution starts from the current state of your workspace and the current version of the definition.

One property deserves candor: routine runs execute unattended, with tool actions pre-approved for the session — that is what makes scheduled work possible at three in the morning. Treat an enabled routine as trusted authority: read its body before enabling it, keep its instructions narrow, and rely on the approval gates below for anything outbound. The shipped catalog is written to that standard.

Reliability

The engine assumes runs will sometimes fail and is built to degrade loudly rather than thrash:

• Retries with backoff. A failed run retries up to twice within its tick — immediately, then after 60 seconds, then after 120.
• Self-disable. Three consecutive failed ticks disable the routine and drop its schedule until you re-enable it. A single transient blip does not count against it once any attempt in the tick succeeds.
• A bounded pool. At most 8 routine jobs run at once platform-wide, with a queue behind the cap — a busy schedule queues work instead of swamping your machine. Individual routines can carry their own tighter cap.
• Crash recovery. If the daemon is killed mid-run, claimed work items are released on the next start — nothing is stranded half-claimed.

Every run leaves a trail

• A per-run log file under documents/routine_logs/<routine>/, timestamped to the second, containing the run's configuration, its full output, and a status footer with duration and exit code.
• A live registry — an auto-maintained table of every routine, its cadence, enabled state, last run, and outcome, kept as a Markdown file in the same folder.
• Job history in the Routines view — recent runs with status badges, plus live output tabs while a run is in flight.

When a routine misbehaves, the log is the first stop: it shows exactly what the session saw and did, run by run.

Where approval sits

Most of the catalog automates up to the last mile and stops before the outside world. Where it does not, the reason is a switch you set:

• The newsletter routine cannot send. It writes a draft with a pending status and has no send path; dispatching the newsletter is a separate, explicit action.
• The email routines can send, and the decision is which one you enable. Both ship disabled, and each carries its own send policy. The general email-agent ships with auto-send on: enable it and a reply-disposition draft that passed the agent's confidence gate goes out without waiting for you. The support variant ships with auto-send off — it drafts, you approve. A routine's own setting wins over the install-wide email.auto_approve_drafts, which ships off, and over both sits the Email sending control plane, which refuses every send while it is off, including yours. Read the Auto-send switch on the row before you arm it. The whole model is on Autonomy and controls.
• Pipeline routines wait for your gates. The product-pipeline routines each execute one stage and stop; you approve between stages.
• Housekeeping auditors are read-only. The consistency and review routines report drift — they do not repair state on their own, and the graph-cleanup routine defaults to a dry run that only proposes.
• A scheduled dispatch works at the level its entry carries. The schedule-executor routine is what a Calendar entry fires, and how far that run may reach is set on the entry, not here.

What it costs

Routine runs draw on your own agent CLI subscription, like every agent run — the platform never sits between you and your model. Spend is the product of cadence, model, and how much work each run finds:

• The model field is the dial. Most of the shipped catalog runs on Sonnet; the Opus routines are the analysis-heavy ones, and every routine's model is in the tables below.
• Only one shipped routine states an engine at all, and it names the same one everything else inherits — so out of the box the whole catalog executes on your install's default engine. The field is there for the case where you want a particular routine to run somewhere else.
• A 30-minute cadence with nothing new to process costs little — the shipped routines check for work first and exit quickly when there is none — but an unattended schedule does spend while you are away.
• Start conservative: enable a routine, read a few logs, then widen the cadence once it has earned trust.

The catalog

Cadences below are the definitions' defaults; whether each schedule is armed is always your switch in the Routines view.

Intelligence production

The products pipeline

On-demand stages of the products chain — the Products view dispatches them, and each carries its own concurrency cap so parallel products cannot pile up:

Knowledge graph upkeep

Email

Both work the mail queue rather than a clock, and both ship disabled. You arm and trigger them from the Email view's Agent tab, which is also where each one's mailbox scope and Auto-send switch live:

The support routine is a variant, and variants are how per-mailbox policy is expressed: any definition named email-agent-<name> is discovered automatically and carries its own account scope and its own send-versus-draft setting. Cloning one is how you add a mailbox with a policy of its own.

Scheduled dispatch

This one is not a routine you schedule — leave its own schedule off. The Calendar's clock dispatches it, once per firing, and every agent-dispatched entry goes through it. It is also exempt from the failure counter, the auto-disable and the retry ladder above, for a structural reason: every entry shares this one routine and failure state is keyed by routine name, so three bad entries in a row would otherwise switch off the mechanism the whole schedule runs on. A failed firing is recorded against its own occurrence instead, and is not retried blindly — the occurrence is already claimed, and a re-run would execute the same brief twice.

Housekeeping & consistency

Where to go next

• Routines & automation — when to reach for a routine at all
• Agent pipelines — the chains these routines dispatch
• Daemons — the automation engine as a running service
• Catalogs — the flat routine table