Agent Scheduling

Updated August 4, 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: Ask Every Time, Smart, or Auto for the scheduled run.
  • Isolated worktree (optional): run on its own branch so ordinary in-repo edits stay in a separate working directory while you’re away. This is not an OS sandbox; 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

Scheduling is free up to 3 active schedules on every tier — create, list, and cancel them from the desktop, CLI, or phone, and existing schedules keep running. Past three, crystl schedule add returns 403 limit_reached; a Guild membership lifts the cap.