Crons
tackroom cron lists every scheduled job on your machines, runs and pauses launchd jobs, and installs jobs you declare as native units of the host's own scheduler. Use it to see what runs where and whether it ran, and to keep your own jobs in your config repo. tackroom runs no scheduler daemon of its own.
tackroom cron collect [--hosts local,HOST...] [--table] # read-only inventory, JSON by default
tackroom cron run|pause|resume [--host HOST] ID # act on a launchd job, here or over SSH
tackroom cron schedule ID "MIN HOUR DOM MON DOW" # new schedule for a job tackroom owns here
tackroom cron apply [--dry-run] # install, replace or remove declared jobs
tackroom cron add|edit|remove ID [flags] # declare, change or delete an owned job, then apply
tackroom cron [--interval 15m] [--deps] [--remove] # tackroom's own sync job
run, pause, resume and schedule also take --source (default launchd) and --config PATH.
See every job
tackroom cron collect --table lists the jobs on each of your hosts; without --table it prints JSON, one record per job (The record). The table output is the access table, which says what each host's scan could read (Access states), then the jobs, then the Outputs and Problems lists, so the jobs and what failed are the last lines on screen. On a terminal narrower than the full tables, a table loses its borders, then the problems, runs, source and schedule columns, and shortens the id in the middle and the last run to MM-DD HH:MM, until it fits; a last run that failed shows exit N in red. Into a pipe or a file every column stays.
For each host, collect runs one POSIX sh probe, locally or through ssh -o BatchMode=yes HOST sh -s, and parses the printed scheduler state locally. Nothing is installed on, copied to or written on the scanned host.
- Hosts come from
--hosts, elsecrons.hostsintackroom.local.yaml, elsecrons.hostsintackroom.yaml, elselocal. SSH aliases resolve through your own~/.ssh/config. - The same list names the machines
tackroom hostsreports on: tackroom's own version, sync state and config commit on each (commands.md). - Scope is the user tackroom runs as (or the SSH user): their LaunchAgents, crontab and user timers. System daemons, other users' crontabs and system timers are out of scope.
| Source | Read from | Included |
|---|---|---|
launchd |
~/Library/LaunchAgents/*.plist and launchctl print |
Jobs with StartCalendarInterval or StartInterval. KeepAlive, RunAtLoad and other on-demand agents are services: listed only when their last exit is non-zero, with state: service. |
crontab |
crontab -l |
Every schedule line; @reboot is left out. |
systemd |
systemctl --user timers and their units |
User timers systemd has loaded. |
codex |
Codex's automations database (needs a local sqlite3) |
Every automation. |
claude-desktop |
The Claude desktop app's scheduled-tasks.json |
Every scheduled task. |
herdr-automations |
automations.yaml and history.jsonl of the herdr-automations plugin |
Every automation. When its scheduler process is not running, every enabled automation is dead. |
claude-cloud |
nothing | Reported as not_scanned: cloud routines have no on-disk state. |
collect also reports one access entry per host and source, so an empty list is never ambiguous (Access states).
What collect flags
- launchd ignores keys it does not recognize. A
StartCalendarIntervalwritten withhourandminuteis an empty interval, which launchd fires every minute.collectflags an entry with no recognized key, any key that matches a known one only in a different case, and unknown keys. - An absolute path in a launchd command, a crontab line or a systemd unit that does not exist is flagged. Redirect targets are skipped.
- A launchd
KeepAliveservice with 10 or more runs and a non-zero last exit is flagged as a crash loop. The threshold is a heuristic. - A launchd job killed by the system (for example
OS_REASON_CODESIGNINGafter its binary was overwritten in place) is flagged. - A scheduled job whose recorded last run is older than the two most recent times it should have fired is flagged as "enabled, but has not run". This runs only for Claude desktop and herdr-automations, where the scheduler records its own last run.
Run, pause and resume jobs
tackroom view has a Crons tab with the same inventory. It collects on first open, caches for a minute and collects again on request. Jobs that need attention come first, then one table per host with an access chip per source. A job needs attention when it has problems or is dead or missing; a paused job's old error does not count until it is turned on again.
Only launchd jobs have actions. crontab, systemd timers and the other sources are read-only.
- A launchd job's row offers Run now, Pause and Resume; an owned job on the machine the view runs on also takes a new schedule.
- The tab has an Add cron button, and an open row of a job tackroom owns here has Edit and Delete. Any other row has neither, and says why (
edit_note). - The CLI verbs do the same for scripts and other clients, such as the Herdr panel.
tackroom dash, the live screen the terminal workspaces open, runs, pauses and resumes a launchd job too, after a y/n question: Enter runs the selected job now,ppauses or resumes it. It does not pause a launchd service, becausecollectleaves a disabled service out and nothing would be left to resume.
What each action runs:
- Run is
launchctl kickstart gui/$UID/<label>. - Pause is
launchctl disablethenbootout, so the job stays off across logins andcollectreports itdisabled. - Resume is
launchctl enable, thenbootstrapof the plist when it is not loaded. - On another host the same script runs over SSH.
- A schedule change rewrites
crons.jobs.<id>.schedulein the file that declares the job (tackroom.local.yamlwhen it has the id, elsetackroom.yaml), then runscron apply. A paused job must be resumed first.
How a client addresses a job and what it gets back is in Action requests.
Record who made a job
Who created a job and what it touches cannot be derived from a command line, so you declare it once. collect merges declared fields into the record with the same scheduler-native id, narrowed by host and source when set.
crons:
hosts: [local, laptop, vps]
jobs:
com.example.backup: # scheduler-native id
host: laptop # optional
source: launchd # optional
created_by: human
connectors: [git, ssh]
effect: nightly commit pushed to the backup remote
output: $KNOWLEDGE_DIR/research/backup/*.html # optional: where results land, a path or glob
A declared job that collect cannot find is reported as state: missing, but only when every place it could live was read: the host was reached and its source came back found or empty, or, with no source, no source on that host came back unreadable.
Declare your own jobs
A job with a schedule and a command is owned: tackroom writes it as a native unit and removes it when the declaration goes. Agent prompts on a schedule are not owned jobs; use herdr-automations for those.
crons:
scheduler: auto # auto | launchd | systemd | crontab
jobs:
notes-sync:
host: m1 # matched against crons.self; omit to run on every machine
schedule: "*/30 * * * *"
command: [~/.local/bin/notes-sync]
created_by: human
Then run tackroom cron apply. It loads the config, takes a lock at ~/.local/state/tackroom/cron/apply.lock, reads every owned unit on the machine, and prints a plan per id: install, replace or remove. --dry-run stops after the plan and prints the units. A missing or invalid config stops it; it never reads one as an empty manifest.
crons.selfin each machine'stackroom.local.yamlnames that machine. A job is in scope when itshostis unset or equalscrons.self. If any owned job has ahostandcrons.selfis unset,applystops before changing anything.crons.schedulermay also be set locally; the local value wins.- Job ids match
^[a-z0-9][a-z0-9-]{0,62}$, because the id becomes part of file names and unit labels. ~and$HOMEincommandexpand at render time, so units hold absolute paths.
scheduler |
Unit | While the machine is asleep or off |
|---|---|---|
launchd (default on macOS) |
~/Library/LaunchAgents/dev.tackroom.<id>.plist with StartCalendarInterval |
Runs once on wake. |
systemd (default on Linux) |
tackroom-<id>.timer with OnCalendar= and Persistent=true, plus a oneshot service |
Runs once when the user manager starts again. A server needs loginctl enable-linger $USER; apply warns when it is off. |
crontab |
One marked line | Skipped. Only when set explicitly. |
auto never falls back to crontab: when systemctl --user does not answer, apply stops and asks for an explicit scheduler. Output goes to ~/.local/state/tackroom/cron/<id>.log; systemd keeps it in the journal. How the schedule is translated is in How owned units are written.
Add, edit and remove owned jobs
tackroom cron add ID --schedule "MIN HOUR DOM MON DOW" --command CMD [--arg ARG ...] [--host NAME] [--effect TEXT] [--output PATH] [--local]
tackroom cron edit ID [--schedule EXPR] [--command CMD [--arg ARG ...]] [--host NAME] [--effect TEXT] [--output PATH]
tackroom cron remove ID
All three take --dry-run, --no-apply and --config PATH; the id may come before, between or after the flags. --dry-run prints the YAML change and the apply plan and writes nothing. Without --no-apply each runs cron apply after writing, which stays the only writer of native units.
- A command is
--commandplus one--argper argument, in order, stored as a YAML list:--command /usr/bin/git --arg -C --arg /srv/notes --arg pullbecomescommand: [/usr/bin/git, -C, /srv/notes, pull].edit --commandreplaces the whole list. addwritescrons.jobs.<id>totackroom.yaml, or totackroom.local.yamlwith--local.editchanges only the fields you pass, in the file that declares the job (tackroom.local.yamlwhen it has the id).--host "",--effect ""and--output ""remove the field.removedeletes the declaration, from both files when both declare it, with the comment lines directly above it. When that was the last job, thejobs:andcrons:keys that held it go too, so anaddfollowed by aremoveleaves the file as it was; acrons:block with another key or any comment keeps its place.- If
applyfails after the write, the declaration stays saved and the error says so; fix the cause and runtackroom cron apply.
In the web view, Add cron, Edit and Delete do the same. The form takes the name (add only), schedule, command, one argument per line and an optional effect, sends only the fields an edit changed, and shows a refusal in the form. Delete asks first.
tackroom creates, changes and deletes only jobs it owns. Any launchd, systemd, crontab or other job without tackroom's prefix is never touched by these commands, and an id that collect reports but that is not declared is refused with an error that says so.
Refused before anything is written:
- an invalid or reserved id;
- a schedule the
applyparser rejects; - an empty command, or a command not found on
PATHhere (when this machine will install it and--no-applyis not given); - a
hostwhilecrons.selfis unset; addof an id that exists, andeditorremoveof an id that is not declared;- an id that is declared without both
scheduleandcommand. The last kind are inventory annotations; edit them by hand.
How the YAML is written:
- Only the lines of the touched entry are rewritten. Every other byte of the file stays as it was, and comments inside the touched entry are kept but may be re-spaced.
- A file whose
cronssection is in flow style, or has no blockjobsmapping to extend, is re-encoded whole instead. - The write is atomic and keeps the file's mode. No backup copy is made, the same as for a schedule change; the config root is meant to be in git.
Built-in jobs
tackroom cron with no subcommand installs the job setup installs:
tackroom-pullrunstackroom pull(git pull --ff-only, thensync), every 15 minutes by default.--depsinstallstackroom-depsinstead, weekly:tackroom sync depsupdates patch-level dependencies in the config root (Go modules, pnpm, uv) and checks package age.--removeremoves the job;--intervaltakes5m,15m,30m,1h,6h,12h,dailyorweekly.
They are installed through the same planner as apply, on the selected scheduler and off every other, so a self-update cannot end up installed twice. apply never prunes these ids and the manifest cannot declare them. The first tackroom cron also removes an older crontab line that ran tackroom pull, sync deps or deps update for the same job.
While the pull job is missing, paused, broken or its last run failed, status prints a warning and doctor has a periodic sync check. periodic_sync: false (set by setup --no-cron) silences it.
See jobs in Claude Code and Pi
The same view is available inside Claude Code and Pi, from the claude/ and pi/ folders of the repository. Both list the jobs from cron collect and act through tackroom cron run|pause|resume; /tackroom opens them.
How to install them, their options and what else the Claude Code pane does are in plugins.md.
herdr-automations
herdr-automations is a Herdr plugin that schedules agent prompts. tackroom reads it and never writes automations.yaml:
collectreads the plugin's config and history on every scanned host where the config folder exists.- The view shows its records in the Crons tab, and a host card shows whether its scheduler is running.
- On a machine with an
automations.yaml,tackroom doctorreports a scheduler that is not installed as a login service, and agent names in the file that this machine has no binary for.
What it does not do
- It runs no scheduler daemon. Owned jobs are native units that the host's scheduler fires.
- Scheduled jobs are not a sixth sync surface.
collectreads state;applywrites only units with tackroom's prefix; neither writes harness configuration. collectnever changes a job. The view and the action verbs change only a launchd job someone acts on, andadd,editandremovechange only the declaration of an owned job.- It does not ship job output or history anywhere. Everything stays on your machines.
Reference
The record
Each job is one JSON record. Main fields:
| Field | Meaning |
|---|---|
host, source, id, name |
Where it lives and its scheduler-native id. A crontab id is crontab- plus a short hash of the line. |
schedule, tz, command, log |
As the scheduler stores them. |
runs, last_exit, last_status, last_run |
What the scheduler records; last_run may come from a log's mtime. |
state |
scheduled, service, disabled, paused, not_loaded, dead or missing. |
health |
ok, warn, fail, idle or paused, computed once for every view. |
created_by, connectors, effect |
From the manifest (Record who made a job), or inferred. |
output, output_expanded |
Where the job's results land: the declared path or glob, and, for a job on this machine, the same with ~ and environment variables expanded (empty for another host, whose home and environment are not known). --table lists them under "Outputs". |
declared_schedule, declared_command |
The schedule and command list a crons.jobs entry declares, as written. |
editable, edit_note |
editable is true for a job cron edit and cron remove can change from this machine; otherwise edit_note says why not (a job tackroom did not install, one on another host, a note-only entry). |
problems, inferred |
Findings, and the names of fields tackroom derived rather than read. |
Access states
| State | Meaning |
|---|---|
found |
Read successfully, at least one job. |
empty |
Read successfully, no jobs, or the scheduler is not installed. |
unreadable |
The state exists but could not be read: a permission error, a database that will not open, a GUI launchd domain not available to the SSH session. |
not_scanned |
Not attempted: wrong OS for the source, host unreachable, or a documented gap. |
How owned units are written
- Owned units are recognized by prefix:
dev.tackroom.<id>for launchd,tackroom-<id>.timerfor systemd, a# tackroom:<id>marker for crontab. Nothing without the prefix is read as owned or touched. collectmaps an owned unit back to its manifest id by the prefix and marks itcreated_by: tackroomunless the manifest says otherwise.- The schedule is a 5-field cron expression and is translated, never passed through. A launchd job lists restricted fields as keys, and an expression that expands past 64 intervals is refused.
StartIntervalis never used, because it drops firings during sleep.- An expression that restricts both day of month and day of week is refused, since cron runs it when either matches and the other backends cannot say that.
Action requests
- An action addresses a job by host, source and id as the last scan reported it, never by a label or path from the request. The view answers
stale_cronsfor a job that is not in its last scan. - An action answers
{"output", "job"}, wherejobis the job's record from a fresh scan of its host. The web view redraws that one row from it at once, so Pause turns into Resume without waiting; the full collect still runs in the background and does not overwrite a row changed after it began.
The jobs API: POST /api/crons/jobs
The view serves add, edit and remove as POST /api/crons/jobs, with the token, origin and CSRF checks of /api/crons/action. The web view's Add cron, Edit and Delete post to it.
The body is JSON. Unknown fields are refused.
| Field | Meaning |
|---|---|
action |
add, edit or remove |
id |
The job id |
schedule, command, host, effect, output, local, dry_run, no_apply |
As the CLI flags above; command is a list, executable first |
The answer carries:
files: the YAML files written;diff;plan: the linesapplyprinted;job: the job's fresh record from a scan of this machine, so a client can refresh one row (nullafter a removal or a dry run).
Errors use the usual {"error": {"code", "message"}} shape: invalid_request (400) for a malformed body, cron_action_failed (422) for a refusal or a failed apply. A job for another host is refused with a message to edit tackroom.yaml and let that machine run cron apply.