scheduled-jobs

scheduled-jobs

A single, discoverable entry point for "what runs automatically on this Mac, and how do I change it." The deterministic work lives in scheduled-jobs.sh — invoke it as ${CLAUDE_SKILL_DIR}/scheduled-jobs.sh (shortened to scheduled-jobs.sh below). Call it; don't reinvent launchctl inline.

Inventory covers launchd (LaunchAgents + LaunchDaemons) and the user crontab. Claude cloud routines are a separate system — manage those with /schedule.

Commands

scheduled-jobs.sh list [--all]      # markdown table of YOUR jobs; com.apple.* hidden unless --all
scheduled-jobs.sh show <label>      # parsed plist + live launchctl state (last exit, runs, next fire)
scheduled-jobs.sh create --label L (--command "CMD" | --script PATH [-- ARGS...]) \
                         (--at HH:MM | --every SECONDS) [--log PATH] [--run-at-load]
scheduled-jobs.sh run     <label>   # run now (launchctl kickstart)
scheduled-jobs.sh enable  <label>   # load + enable
scheduled-jobs.sh disable <label>   # unload + persistently disable (plist kept)
scheduled-jobs.sh remove  <label>   # unload + move plist to a .removed-<ts> backup (no hard delete)
scheduled-jobs.sh log     <label> [N]  # tail N (default 40) lines of the job's StandardOutPath

How to use it

• "What do I have scheduled?" → list. The table is Label / Scope / Schedule / Command / Loaded / Log. user-agent rows in your home dir are the ones you own.
• "What is job X doing / when does it run / did it fail?" → show X (the launchctl print tail gives last exit code and next fire time).
• "Run X every day at 9am" → create:

  scheduled-jobs.sh create --label com.you.backup --at 09:00 --command "rsync -a ~/src ~/bak"
  scheduled-jobs.sh create --label com.you.report --every 3600 --script ~/bin/report.sh -- --quiet
  

  Present the result, and remember it's a LaunchAgent: it fires when you're logged in and awake (catches up on wake if asleep at the time).
• Turn one off / back on / run on demand → disable / enable / run.
• Delete one → remove (the plist is backed up to *.removed-<timestamp>; tell the user to delete that file to finalize, or enable to restore by re-bootstrapping the original — point them at the backup).

What create bakes in (the launchd gotchas)

• PATH includes /opt/homebrew/bin — launchd's default PATH omits it, and a missing Homebrew tool (e.g. gh) silently breaks the job. HOME is set too.
• Runs via /bin/bash (so a --command string gets a real shell), logging stdout+ stderr to ~/Library/Logs/<label>.log by default.
• LaunchAgents only (user session). That's what makes the macOS keychain reachable (e.g. a gh token) — a LaunchDaemon or bare cron runs outside your session and would need credentials passed in explicitly (GH_TOKEN etc.).
• --at HH:MM → StartCalendarInterval; --every N → StartInterval. The plist is plutil -linted before loading.

Notes / limits

• macOS only. Reads every plist in ~/Library/LaunchAgents, /Library/LaunchAgents, /Library/LaunchDaemons; com.apple.* hidden unless --all.
• The Command column flattens ProgramArguments for readability (arg quoting is lost in the display, not in the actual job).
• loaded for system daemons can read no without root even if active (launchctl print system/<label> may need privileges); user agents are accurate.
• Pairs well with the worktree-cleanup skill in this plugin: use create to schedule its --remove run as a daily LaunchAgent, then list/log to watch it.