All pages

Lesson 4.4 · Automate · 12 min

Schedules and background jobs

Run prompts and commands on a timer, keep the Mac awake, get notified.

Listen

After this lesson you can run a prompt or a command on a timer, keep long commands running after you quit TRMNLY, keep the Mac awake while work is going, and get told when something finishes.

Time: 12 minutes · Works on: macOS app. The cloud workspace has its own Jobs tab with the same schedule syntax.

Two kinds of timer

TRMNLY has two ways to run things later. Pick by one question: does it have to run while TRMNLY is closed?

Scheduled runs Background jobs
Runs A prompt to the agent, or a command in a pane A shell command, out of sight
While TRMNLY is closed No Yes, through macOS's launchd
You watch it In the agent sidebar or the pane In its log
Open it from The agent's gear menu The Jobs tab

Schedule a prompt

  1. Open the Agent tab and click the gear in its header.
  2. Under Automation, choose Scheduled jobs…. A sheet titled Scheduled runs opens.
  3. Click Add.
  4. Give it a Name, such as "Morning summary".
  5. Choose Agent prompt and type the prompt: "Summarize what changed in this repository since yesterday."
  6. In Schedule, type @daily 09:00.
  7. Click Save.

The list shows when each schedule fires next and how its last attempt went. Click Run on a row to fire it now and see what it does. Pause all, at the top, stops every schedule without changing which ones are on.

A scheduled prompt arrives in the agent sidebar as if you had typed it.

Schedule a command instead

Choose Terminal command in step 5. The command is added to the target pane's command queue, so it waits its turn behind whatever is running. Press Enter and Stop the queue on a failure work the same as in the queue.

Write a schedule

The same syntax works in the sheet, in the agent's tools and in the Jobs tab.

Type Means
30s, 5m, 2h, 1d Every N seconds, minutes, hours or days
@hourly On the hour
@daily 09:00 Every day at that time
@weekly mon 09:00 That weekday at that time
@monthly 15 08:00 That day of the month, 1 to 28
0 9 * * 1-5 Standard five-field cron: weekdays at 09:00
in 45m Once, 45 minutes from now
at 14:00 Once, at that time

TRMNLY refuses a schedule it can't read, right where you typed it, so a typo never becomes a schedule that silently never fires.

Options worth knowing

The sheet has more settings. The defaults behave like a plain timer.

  • Quiet hours: a run that comes due outside the window is held until the window opens, not dropped.
  • Days: which weekdays it may run, with 0 for Sunday.
  • Stop after: a number of runs, a date, or both.
  • Make up a run missed while TRMNLY was closed: on by default. Turn it off for anything that only makes sense on time.
  • Only when the pane is idle and Skip while the agent is mid-turn: hold a run instead of stacking it behind other work.
  • Notify me if it stops: on by default, so a schedule that gives up tells you.

You can also ask the agent: "Every weekday at 9, ask me what I'm working on today." It creates the schedule with its schedule_create tool, after you approve.

Run a background job

  1. Show the right sidebar with ⌘⇧\, open More ▾ and choose Jobs.
  2. In Command, type something that takes a while, such as sleep 20 && echo done.
  3. Give it a name in Name (optional).
  4. Leave Schedule empty to run it once, or enter something like 5m or @daily 03:00. Intervals under 10 seconds are refused.
  5. Leave Keep alive off. Turn it on only for something that should be restarted whenever it exits, like a watcher. It can't be combined with a schedule.
  6. Click Submit.

The job runs in the working directory of the tab you were in, through zsh, after loading your ~/.zshrc. Its row shows its state: running, exited (with the exit code if it failed), waiting for its schedule, or unknown.

  • View log shows the end of its output, updated while it runs.
  • Reveal shows the log file in Finder.
  • Stop ends a running job. Remove clears a finished one, including its logs.

When a job finishes, TRMNLY posts a notification with its exit status and the last lines of its log. Logs are kept in ~/Library/Logs/TRMNLY/jobs/.

Try quitting TRMNLY while a job runs. Reopen it and the job has carried on.

Keep the Mac awake

Below the job list is the Awake monitor. It shows everything that's currently keeping the Mac from sleeping, and for how long.

By default, TRMNLY keeps the Mac awake while a command is running in any pane, while the agent is working and while a command queue has work in it. Each hold is released as soon as its reason ends. Change this under Settings → General → Sleep, which also has Idle mode — never sleep while TRMNLY is open.

Each row has a Stop button, and Stop all appears when there are several. Use it when you find a forgotten test runner keeping the fan going.

Two limits: the display still sleeps, and closing the lid still puts the Mac to sleep. For an overnight run, leave the lid open.

Check yourself

  • A scheduled prompt fired when you clicked Run, and shows its next time.
  • A background job kept running after you quit and reopened TRMNLY.
  • You got a notification when the job finished.
  • The Awake monitor listed your running command while it ran.

Go further

  • Scheduled runs — every option, and how held, failed and stopped runs differ
  • Background jobs — where job files live and the agent's job tools
  • Awake — what keeps the Mac awake and what can't