All pages

Docs · AI features

Background jobs

Availability: macOS. Built on launchd.

Long-running commands you want to fire and forget — overnight builds, periodic syncs, cron-style schedules — live in the Jobs tab (right sidebar). TRMNLY runs them through launchd so they survive terminal close, app quit, and system sleep.

Logs land in:

~/Library/Logs/TRMNLY/jobs/

Job definitions are JSON files (plus a shell wrapper script) in ~/Library/Application Support/TRMNLY/jobs/; the launchd plist itself lives in ~/Library/LaunchAgents/. The label is reverse-DNS (com.trmnly.job.<uuid>) and matches the plist filename.

What a job carries

  • Command — the shell command to run. It's wrapped in an interactive zsh that sources your usual rc files, since launchd hands the process an almost-empty environment.
  • Display name — sidebar label; defaults to the command's first token
  • Working directory — captured from the tab the job was created in
  • Keep alive — if on, launchd respawns the process when it exits. Off by default; most jobs are one-shot scripts, not supervised services. Can't be combined with a schedule (the two together would double-fire), so the composer refuses that combo.
  • Schedule — optional. Without a schedule the job runs once (RunAtLoad=true). With one, RunAtLoad flips off and launchd fires the job on the cadence instead.

See Scheduled runs for the other kind of schedule: prompts and commands that fire inside TRMNLY, into the agent or into a pane you can watch. A background job is the right tool when the thing has to run with TRMNLY closed; a scheduled run is the right one when you want to see it happen.

Schedule syntax

The composer accepts:

Form Meaning
5m, 30s, 2h Interval — fire every N seconds/minutes/hours
@daily 09:00 Calendar — every day at 9 am
@weekly Mon 17:00 Calendar — every Monday at 5 pm
(blank) One-shot — run once at load, then stop

Intervals below 10 seconds are rejected — launchd silently ignores faster values, so the editor catches it upfront.

Status

Each row shows its current state, inferred from launchctl list:

  • running (with pid)
  • exited (with exit code; non-zero highlighted)
  • waiting — scheduled, not yet fired
  • unknown — launchd doesn't report a state

Each row offers:

  • View log — expand a tail of the output, refreshed while the job runs
  • Reveal — show the log file in Finder (the .err.log sits next to it)
  • Stop (while running) / Remove (after exit) — unloads the plist and deletes the job's files, logs included

When a job finishes, TRMNLY posts a notification with the exit status and the last few lines of its log.

Agent integration

The agent has tools for the full lifecycle:

  • run_background_job — submit a new job
  • list_background_jobs — enumerate state
  • stop_background_job — kill a running job
  • update_job_progress — agent-reported percent and message, surfaced inline in the sidebar so an LLM-driven job doesn't force you to tail a log

update_job_progress is the difference between watching a fan run for 40 minutes wondering if anything's happening and seeing "Phase 3/5 — 60%" on the job row.

Common patterns

  • Overnight build: command = npm run build:full, no schedule, keep alive off. Comes back in the morning with logs.
  • Periodic sync: command = ~/bin/sync-photos, schedule = @daily 03:00, keep alive off.
  • Background watcher: command = ./watcher, no schedule, keep alive on. Treats failures as restarts.

If a job goes sideways, the first thing to check is the error log — plain text files in the logs directory, one click away via the row's Reveal button.

The Jobs tab also hosts the Awake monitor right below the job list, showing everything currently keeping the Mac awake.