Run agents on a schedule

Updated September 29, 2026

Goal: the overnight test triage, the morning inbox pass, or the nightly backup script 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 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, schedules, and add one. Choose the gem, then pick the target:

    • agent prompt: crystl launches a fresh agent and sends your prompt. You also choose the agent, the model, and the approval mode for that run.
    • command: crystl runs one shell command in a fresh shard with no agent. Pick this when the task is already decided, like bash scripts/backup.sh. No model in the loop means it is faster, it costs no tokens, and it does the same thing every night.
    • sequence: the schedule triggers a sequence you have already written.

  2. Turn on “rotate through a list” if each firing should do a different thing. Add your entries in order and every run takes the next one, wrapping at the end, so five prompts on weekdays give you a different task each weekday.

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

  4. Set the time, cadence, and time zone. Cadence is once, daily, weekdays, or a longer anchored one (weekly, monthly, quarterly, yearly). 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.

  5. 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 "02:00" --repeat daily --command "bash scripts/backup.sh"
crystl schedule add --gem myapp --at "2026-07-21 16:00" --agent codex \
  --model gpt-5.1-codex-max --approval in-gem --isolated --prompt "prepare the release branch"
crystl schedule list
crystl schedule cancel 7A4F2C91

    Pass exactly one of --prompt or --command. Repeat either flag to build a rotation.

What you’ll see when it works

The schedules panel lists every schedule, 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: a prompt arrives as an agent’s first message with your chosen approval mode, and a command runs in the shard’s shell.

A command schedule also tells you how the run went: succeeded, failed with its exit code, no start seen, or unknown. Read “unknown” as “crystl could not tell”, never as success. A failed run raises a card naming the command that ran and keeps the shard so you can read the scrollback.

After sleep or a restart, an overdue schedule runs once as catch-up rather than firing for every slot it missed. A rotation advances one position on that catch-up, the same as any other firing, so a missed day shifts the rest of the list along by one.

A scheduled agent run still respects your auto-approve posture, so pick it deliberately: an unattended run with auto-approve off will sit and wait for you. A command schedule has no approvals to wait on.

Go deeper