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
zshthat 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,RunAtLoadflips 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.logsits 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 joblist_background_jobs— enumerate statestop_background_job— kill a running jobupdate_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.