All pages
Docs · AI features
Scheduled runs
Availability: macOS (the app's own scheduler) and the cloud workspace (the Jobs tab). The two share a schedule vocabulary; they do not share a store.
Anything TRMNLY can queue, it can also schedule: a prompt to the agent, a command into a terminal pane, or a run in your cloud box — on a cron, on a fixed interval, or once.
- Mac, by hand: agent settings menu → Scheduled runs.
- Mac, from the agent:
schedule_create,schedule_list,schedule_update,schedule_delete,schedule_run_now. - Cloud: the Jobs tab, or the
job_*tools over MCP.
Schedules on the Mac fire while TRMNLY is running. For something that has to run with the app closed, use a background job — it hands the command to launchd. Cloud jobs run whether or not anything of yours is open.
Schedule syntax
The same grammar in the editor, in the tools, and in the composer for background jobs.
| Form | Meaning |
|---|---|
30s 5m 2h 1d |
Every N seconds/minutes/hours/days, measured from the last run |
120 |
Bare number: seconds |
@hourly |
On the hour |
@daily / @daily 09:00 |
Midnight, or the time you give |
@weekly mon 09:00 |
That weekday, at that time |
@monthly 15 08:00 |
That day of the month (1–28) |
0 9 * * 1-5 |
Five-field cron: minute, hour, day-of-month, month, day-of-week |
in 45m |
Once, that long from now |
at 14:00 / at 2026-09-08 14:00 |
Once, at that moment |
Cron accepts *, a, a-b, a-b/n, */n, and comma lists. Day-of-week 0
and 7 are both Sunday. When both day fields are restricted, a match on
either counts — the standard crontab rule.
An expression the parser cannot read is refused where you typed it, because a
stored schedule that cannot be parsed is a schedule that silently never fires.
One it can read but that has no run coming shows next: nothing in the next
nine days rather than "never" — 0 9 30 2 * (February 30th) genuinely never
matches, but 0 9 29 2 * is a leap day and will fire, and from a nine-day
search those two look identical. The cloud says the same thing over eight days.
A new cron schedule does not fire for a slot that happened before you created
it: creating @daily 09:00 at 09:30 waits for tomorrow. An interval schedule
does start immediately — "every 5 minutes" means starting now.
Timezone. The Mac reads cron fields in your local zone, or in a zone you set per schedule. Cloud jobs default to UTC and take an IANA zone per job.
What a schedule fires
Agent prompt — delivered to the agent sidebar as a user turn, exactly as if you had typed it. Scope it to a project and it only lands in that project's sidebar; with no sidebar to take it, it waits rather than firing elsewhere.
Terminal command — appended to the target pane's command queue, so it drains through the same path a hand-queued command does, including stop the queue on a failure. On a pane sitting at a prompt it runs immediately; behind a running command it waits its turn.
Cloud job — either a headless Claude Code run (kind: agent, with a landing
mode of PR / push / report) or a shell command in your box (kind: command).
Both report back with their output, and email you if you asked them to.
Options
Every schedule carries a policy. The defaults reproduce the behaviour of a plain timer, so you only have to think about these when a timer isn't enough.
| Option | What it does |
|---|---|
| Timezone | IANA zone the cron is read in. Defaults to this Mac's zone (cloud: UTC). |
| Catch up | Make up a slot missed while TRMNLY was closed, within a day. On by default. Turn it off for anything whose value depends on running on time — a backup that starts six hours late is worse than one that waits for tomorrow. |
| Quiet hours | 09:00–18:00, or 22:00–06:00 to wrap midnight. A run due outside the window is held, not dropped: it fires when the window opens. |
| Days | Which weekdays it may fire, 0 = Sunday. Mostly for interval schedules — a cron can already say 1-5. |
| Jitter | Random delay of up to N seconds. For when several schedules share a slot and you don't want five agents starting at once. |
| Stop after | A run count, a date, or both. The schedule disables itself and says why. |
| Give up after | Consecutive failed deliveries before the schedule disables itself. 0 (the default) retries forever, which is right for "no window open right now". |
| Backoff | Seconds × attempt count between retries, capped at an hour. |
| Only when the pane is idle | Terminal targets: hold rather than stack a scheduled run behind a long build. |
| Skip while the agent is mid-turn | Agent targets: hold rather than queue behind the current turn. |
| Notify me if it stops | A notification when the schedule gives up or finishes. On by default — a schedule that silently stopped is the thing worth hearing about. |
Pause all in the sheet header stops every schedule at once without touching which ones are individually on. Schedules keep their last-run stamps while paused, so resuming behaves like the app having been closed.
Reading the list
Each row shows what it does, when it fires, when it fires next, and the outcome of the last attempt. That last line is where "No terminal window for that project — will retry" shows up; without it, a schedule that cannot find its target looks identical to one that simply isn't due yet.
Three things can happen to a due run, and they are different:
- Held — quiet hours, a busy pane, jitter. Nothing is consumed; it runs when the gate opens.
- Failed — nothing was there to take the delivery. Retried, and counted against give up after.
- Stopped — the run limit, the expiry, or too many failures. The schedule is disabled and says which.
A one-shot disables itself once it has fired and stays in the list showing when it ran, rather than vanishing — a schedule that fired and one that was never created should not look the same.
Where it is stored
Mac schedules live in ~/Library/Application Support/TRMNLY/agent/schedules.json
as plain JSON, with the schedule written as the same text you typed. Cloud jobs
live in the site database and are dispatched by a cron that ticks every 15
minutes, so a cloud job starts at the first tick at or after its minute.