<!-- Markdown mirror. Canonical: https://empryo.com/docs/tools/routines -->

# Routines

> Repo-scoped cron routines: /schedule runs headless agent turns on a cron pattern while Empryo is open. Nightly reviews and recurring checks, no system service.

## Overview

A routine is a headless agent run on a cron schedule, scoped to the repo it lives in. Add one with `/schedule` and it fires as a detached `empryo --headless` run of the same binary - a nightly review, an hourly check, a recurring cleanup prompt.

The TUI is the daemon: routines run only while Empryo is open on the repo. Nothing is installed system-wide, no background service survives quitting.

## Commands

| Command | Action |
|---------|--------|
| `/schedule` | List routines and the runner state |
| `/schedule add <5-field cron> <prompt>` | Add and arm a routine |
| `/schedule remove <n or id>` | Remove by list index or id |
| `/schedule on <n or id>` / `/schedule off <n or id>` | Enable / disable |

Example:

```
/schedule add 0 22 * * * review the day's uncommitted work and summarize risks
```

The pattern is validated when you add it - by the same engine that will run it - so a routine that cannot fire is refused up front.

## Plain-word schedules

The cron pattern is optional. `/schedule add` accepts a sentence with the schedule as a
trailing flag, and every human form maps to a real cron pattern that is validated before
the routine is armed:

```
/schedule add review repo for new PRs --every 30m
/schedule add summarize the day --daily 18:00 --mode auto
/schedule add deep audit --every monday 08:00 --model anthropic/claude-opus-4-6
```

| Form | Fires |
|------|-------|
| `every 15m` · `every 2h` · `hourly` | On the interval |
| `daily` · `daily 09:30` | Every day (09:00 when no time is given) |
| `weekdays 18:00` | Monday to Friday |
| `every monday 08:00` · `weekly` | One day a week (Monday 09:00 by default) |
| A raw 5-field pattern | Unchanged |

Flags on the sentence set the run: `--mode`, `--model`, `--agent`, `--name`, and `--bare`.

## Bare runs

`--bare` runs the routine with **no repo and no tools** on the smallest prompt in the
engine, one sentence in, one answer out, roughly 20× cheaper per fire. Use it for
anything that is not repo work: a standup line, a reminder, a summary of text you supply.
Leave it off for anything that must read files, search, or run commands.

## From an agent, and headless

The agent has the same control through the `routine` tool, `list`, `add`, `remove`,
`enable`, `disable`, `run` (fire now, overlap-guarded). A routine's prompt can itself be
an orchestration: `/orchestrate <graph-id> <input>`.

```bash
empryo --headless --routines     # the daemon: arms this repo's routines until Ctrl+C
```

On the desktop, routines and their run history live under **My tools → Routines**
([the workbench](/docs/surfaces/workbench#my-tools)).

## How a tick runs

- Each tick spawns a detached headless run: your prompt, this repo as the working directory, quiet output.
- Overlap-guarded per routine: a tick that lands while the previous run is still going is skipped and counted. Two concurrent agent runs would fight over one tree.
- The last run's time and exit code are recorded and shown in `/schedule`.

## Where routines live

`.empryo/schedules.json` in the project - one file per repo, edited by the command, read when the TUI boots. Routines are repo-scoped on purpose: a nightly review belongs to the repo it reviews.