Schedule Agents · crystl

New Schedule

Name: nightly review
Target Gem: webapp

Repeat: once, daily, weekdays
When:
July 18, 2026, 9:00 AM
Time Zone: America/Los_Angeles

Agent: default agent
Model: model (optional)
Approval Mode: default, isolated worktree

Prompt

Review the overnight create schedule

A schedule runs one of two things at a time you choose. An agent prompt launches a brand-new agent shard carrying the same launch choices you'd make by hand (target gem, task prompt, agent, model, approval mode, and an optional isolated worktree), so the scheduled run is a full, real session. A command runs one shell line in a fresh shard with no agent at all, which is what you want when the task is already decided: bash scripts/backup.sh does not need a model to type it, and putting one in the loop only makes the run slower, less predictable, and more expensive.

One schedule can also rotate through a list. Add your tasks in order and each firing takes the next one, wrapping at the end, so five prompts on weekdays give you a different task each weekday instead of five separate schedules. Rotation works for prompts and for commands.

Pick the cadence that fits: once for a one-off reminder-with-hands, or daily, weekdays, weekly, monthly, quarterly, and yearly for the recurring passes. Times are interpreted in the time zone you set, so "9:00 AM" means 9:00 where you are.

Create and manage schedules from the Settings → Agents → Schedules panel, or drive them from the crystl CLI: crystl schedule add, schedule list, and schedule cancel. Name a schedule, see what's upcoming, and edit or cancel it any time. crystl has to be running and the gem open when the time comes. An overdue schedule runs once as catch-up rather than firing for every slot it missed.

Why It Matters

Once or Any Cadence

Fire a one-off at a specific date and time, or set a recurring cadence: daily, weekdays, weekly, monthly, quarterly, or yearly, anchored to the date you pick.

An Agent or No Agent

Schedule a prompt and get a real agent session. Schedule a command and get one shell line in a fresh shard, no model in the loop, no tokens spent, the same result every run.

Rotate Through a List

One schedule, an ordered list of tasks. Each run takes the next entry and wraps at the end, so a weekday schedule can do something different every day of the week.

Time-Zone Aware

Set the IANA zone once and times mean what you'd expect. 9:00 AM is 9:00 where you are, not UTC, and daylight saving is handled for you.

Outcome Reporting

A scheduled command reports its outcome: succeeded, failed with its exit code, no start seen, or unknown. A failure raises a card naming the command that ran and keeps the shard so you can read the scrollback.

Pick the Agent and Model

Schedule Claude, Codex, or another agent, and pin a model version if the task needs it, the same choices you'd make spinning a shard up by hand.

Isolated Worktree Option

Flip on an isolated worktree and ordinary in-repo edits land on the scheduled run's own branch while you're away.

Read the Scheduling docs →

Try It Yourself

A free account and a download. macOS only, for now.

Get Started Getting Started Guide →

Frequently Asked Questions

  1. How do I schedule an agent?
    Two ways: the Settings → Agents → Schedules panel, or the crystl CLI: crystl schedule add --gem --at "09:00" --every weekdays --prompt "...". Use crystl schedule list to see what's queued and crystl schedule cancel to remove one.

  2. Can a schedule run a command instead of an agent?
    Yes. Pick the command target in the schedule form, or pass --command instead of --prompt, and crystl runs one shell command in a fresh shard with no agent at all.

  3. Can one schedule do a different thing each day?
    Yes. Turn on "rotate through a list" (or repeat --prompt / --command on the CLI) and the schedule holds an ordered list.

  4. What recurrence options are there?
    Once (a one-off at a specific date and time), daily, weekdays (Monday–Friday), or longer anchored cadence: weekly, monthly, quarterly, or yearly.

  5. What can I configure per schedule?
    For an agent prompt: target gem, task prompt, agent, model, approval mode, isolated worktree.

  6. How do I know whether a scheduled command worked?
    Every command run reports an outcome: succeeded, failed with its exit code, no start seen, or unknown.

  7. Is scheduling free?
    Yes. Up to 3 schedules on every tier, agent or command, rotating or not.