# Agent Scheduling

> Schedule a fresh agent to launch at a set time — once, daily, or weekdays — with its own gem, prompt, agent, model, and approval mode.

Some work should just happen on its own: the overnight test triage, the morning inbox pass, the pre-standup release check. A **schedule** launches a brand-new agent shard at a time you choose — once or on a cadence — so the run happens without you at the keyboard.

Each schedule carries the same launch choices you'd make by hand, so a scheduled run is a full, real session, not a bare cron one-liner.

## What a schedule carries

- **Gem** — the project the agent starts in.
- **Prompt** — the task, sent as the agent's first message when it launches.
- **Agent** — Claude, Codex, or another supported agent.
- **Model** — pin a specific model version if the task needs it.
- **Approval mode** — Manual, Smart, or Auto for the scheduled run.
- **Isolated worktree** *(optional)* — run on its own branch, safe for anything that edits files while you're away. See [Isolated Sessions](/docs/isolated-sessions/).

## Cadence and time zone

Pick the cadence that fits:

- **once** — fire a single run at a specific date and time.
- **daily** — every day at the chosen time.
- **weekdays** — Monday through Friday.

Times are interpreted in the **time zone you set** (an IANA zone like `America/Los_Angeles`), so "9:00 AM" means 9:00 where you are, not UTC. Daylight saving is handled for you.

## Creating a schedule

Open **Settings → Agents → Schedules** and add a schedule: choose the gem, write the prompt, pick the agent, model, and approval mode, toggle an isolated worktree if you want one, then set the time, cadence, and time zone. The panel lists every upcoming schedule so you can edit or cancel any of them.

## When a schedule fires

At the due time, crystl creates a **fresh shard** using the normal agent / model / approval path and sends the prompt — you get a proper agent session picking up the task, not a detached shell command.

crystl must be **running** and the target **gem open** for a schedule to fire. After sleep or a restart, an overdue schedule runs **once as catch-up** rather than firing repeatedly for every missed slot.

## From the CLI

The same schedules are scriptable through the [crystl CLI](/docs/cli/#schedule), so an agent or a shell script can set them 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
```

`schedule` without a subcommand defaults to `schedule list`.

## Availability

Reading schedules is free: `crystl schedule list` (and the Schedules panel) work on every tier. **Creating or cancelling** a schedule is a **[Guild](/pricing/)** action — `crystl schedule add` / `crystl schedule cancel` return `403 guild_required` on the free tier, in line with the rest of the CLI's control commands.

---
Source: https://crystl.dev/docs/schedule-agents/