launchd-kit

Shared tooling for managing local LaunchAgents.

What Lives Here

• bin/: install/uninstall/reload/status/log helpers
• plist-monitor/: Discord webhook monitoring
• plist-status.py: terminal status dashboard
• templates/: plist templates

Environment Variables

• LAUNCHD_LABEL_PREFIX (default: com.user.)
• LAUNCHD_PLIST_GLOB (default: */<prefix>*.plist)
• LAUNCHD_INSTALL_DIR (default: ~/Library/LaunchAgents)
• PLIST_MONITOR_ENV (optional .env path override)

Typical Usage (local wrapper justfile)

In each repo, add a small justfile that calls launchd-kit/bin/*.

Example:

• just install → ~/dev/launchd-kit/bin/launchd-install '*/com.user.admin.*.plist'
• just status → ~/dev/launchd-kit/bin/launchd-status

Creating Jobs

See docs/new-job.md and the generator:

• bin/launchd-new-job

Monitoring

plist-monitor scans all loaded agents by prefix (defaults to com.user.). You can override the filter via LAUNCHD_PREFIX_FILTER in the monitor's environment.

Suggested model:

• One global monitor job (e.g., in admin) with LAUNCHD_PREFIX_FILTER=com.user. to watch all agents.
• Domain repos only define their own jobs; they don't need their own monitor unless you want per-domain alerts.

Recommended Job Layout

In each repo, keep jobs self-contained:

• jobs/<job>/job.sh
• jobs/<job>/com.user.<domain_id>.<job>.plist
• jobs/<job>/README.md

If you prefer existing layouts (e.g., scripts/ + *.plist), keep them; just point the glob in your wrapper justfile.