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.

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. That is the right choice when the task is already decided, like bash scripts/backup.sh: no model in the loop means it is faster, it spends no tokens, and it does the same thing every run. A command schedule takes no agent, no model, and no phone reminder.

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. Each firing takes the next entry and wraps at the end, so five prompts on weekdays give a different task each weekday. Up to 31 entries, prompts or commands, not a mix. Rotation counts positions rather than weekdays, so a missed run or a timing edit can shift which entry lands on which day; the detail view always shows which one fires next.

What recurrence options are there?

Once (a one-off at a specific date and time), daily, weekdays (Monday–Friday), or a longer anchored cadence: weekly, monthly, quarterly, or yearly. Times are interpreted in the IANA time zone you set, with daylight saving handled for you.

What can I configure per schedule?

For an agent prompt, the same choices as launching a shard by hand: target gem, task prompt, agent (Claude, Codex, and others), model, approval mode, an optional phone reminder, and an optional isolated worktree. For a command, the gem, the command itself, and the isolated worktree option. You can also give any schedule a name so it's easy to find later.

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. "Unknown" means the command ran and crystl could not see how it went, so never read it as success. A failed run raises a card naming the command that ran and keeps its shard open so you can read the scrollback.

Yes. Up to 3 schedules on every tier, agent or command, rotating or not. A rotating schedule counts as one however many payloads it holds. Create, list, and cancel them from the desktop, CLI, or phone. Past three, a Guild membership lifts the cap.

Schedule agents to run while you are away

guild membership

Tired of staring at a terminal all day? Schedule an agent prompt or a plain shell command, once or on a cadence, and review the work in the morning.

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.

You find out how it went

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

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.
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. That is the right choice when the task is already decided, like bash scripts/backup.sh: no model in the loop means it is faster, it spends no tokens, and it does the same thing every run. A command schedule takes no agent, no model, and no phone reminder.
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. Each firing takes the next entry and wraps at the end, so five prompts on weekdays give a different task each weekday. Up to 31 entries, prompts or commands, not a mix. Rotation counts positions rather than weekdays, so a missed run or a timing edit can shift which entry lands on which day; the detail view always shows which one fires next.
What recurrence options are there?: Once (a one-off at a specific date and time), daily, weekdays (Monday–Friday), or a longer anchored cadence: weekly, monthly, quarterly, or yearly. Times are interpreted in the IANA time zone you set, with daylight saving handled for you.
What can I configure per schedule?: For an agent prompt, the same choices as launching a shard by hand: target gem, task prompt, agent (Claude, Codex, and others), model, approval mode, an optional phone reminder, and an optional isolated worktree. For a command, the gem, the command itself, and the isolated worktree option. You can also give any schedule a name so it's easy to find later.
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. "Unknown" means the command ran and crystl could not see how it went, so never read it as success. A failed run raises a card naming the command that ran and keeps its shard open so you can read the scrollback.
Is scheduling free?: Yes. Up to 3 schedules on every tier, agent or command, rotating or not. A rotating schedule counts as one however many payloads it holds. Create, list, and cancel them from the desktop, CLI, or phone. Past three, a Guild membership lifts the cap.

Book of Spells

the crystl guild

Crystl's Book of Spells

Master crystl with a grimoire of powerful prompts. Summon heroes, assemble a party, revive shards, and complete epic quests.

open the book →

Schedule agents to run while you are away