Agent Scheduling

Updated July 20, 2026

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.

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, so an agent or a shell script can set them up:

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 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.