# Run agents on a schedule

> Launch a fresh agent at a time you choose, once or on a cadence, with its own gem, prompt, agent, model, and approval mode.

**Goal:** the overnight test triage or the morning inbox pass happens without you at the keyboard.

## What you need

- crystl **running** and the target **gem open** at the due time. A schedule launches a real shard, so there has to be an app to launch it in.
- Scheduling is **free up to 3** active schedules on every tier, from the desktop, the CLI, or the phone. Past three, `crystl schedule add` returns `403 limit_reached` and a [Guild](/pricing/) membership lifts the cap.

## Steps

1. **Open Settings → Agents → Schedules** and add one. You choose the gem, the prompt (sent as the agent's first message), the agent, the model, and the approval mode for that run.
2. **Toggle an isolated worktree** if you'd rather the run happen on its own branch while you're away. That's the same worktree system as [isolated sessions](/docs/isolated-sessions/), not an OS sandbox.
3. **Set the time, cadence, and time zone.** Cadence is **once**, **daily**, or **weekdays**. Times are read in the IANA zone you set, like `America/Los_Angeles`, so 9:00 AM means 9:00 where you are. Daylight saving is handled for you.
4. **Or do it from the CLI,** which is how an agent sets up its own follow-up:

   ```bash
   crystl schedule add --gem myapp --at "09:00" --repeat daily --prompt "triage the morning inbox"
   crystl schedule add --gem myapp --at "2026-07-21 16:00" --agent codex \
     --model gpt-5.1-codex-max --approval smart --isolated --prompt "prepare the release branch"
   crystl schedule list
   crystl schedule cancel 7A4F2C91
   ```

## What you'll see when it works

The schedules panel lists every upcoming run, so you can edit or cancel any of them, and `crystl schedule` on its own prints the same list. At the due time a **fresh shard** appears in the gem and the prompt arrives as its first message. It's a proper agent session with your chosen approval mode, not a detached shell command.

After sleep or a restart, an overdue schedule runs **once as catch-up** rather than firing for every slot it missed.

A scheduled run still respects your approval posture, so pick it deliberately: an unattended run in Ask Every Time mode will sit and wait for you.

## Go deeper

- [agent scheduling](/docs/schedule-agents/) for everything a schedule carries.
- [approval modes](/docs/approval-modes/) before you leave a run unattended.
- [Only get interrupted when an agent needs you](/docs/scenario-only-interrupt-when-needed/) and [supervise from your phone](/docs/scenario-supervise-from-your-phone/) for catching a scheduled run that stops to ask something.

---
Source: https://crystl.dev/docs/scenario-run-agents-on-a-schedule/