Run agents on a schedule

Updated August 10, 2026

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 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, 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:

    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