launchd-doctor
Your LaunchAgent is "loaded" but never runs. Or it runs 84 times a day. Or it
exits 78 and writes nothing at all. launchd-doctor finds the macOS launchd
bugs that fail silently, explains them in plain English, and fixes them.
$ launchd-doctor
✗ com.me.nightly-report
StandardOutPath is inside ~/Documents. launchd can't open files there, so the job
fails with exit 78 and no output at all. Move logs to ~/Library/Logs. [fixable]
✗ com.me.backup
StartCalendarInterval has Hour and Minute in separate dicts: fires 84x/day instead of 1x. [fixable]
✗ com.me.ollama
last run exited 1: the program exited with an error — check its log
KeepAlive job has started 159 times and isn't running — crash loop?
137 agents scanned, 3 with problems. Run `launchd-doctor fix` to see automatic fixes.
$ launchd-doctor fix --apply # backs up each plist, rewrites it, reloads the job
Single file, Python stdlib only, macOS 12+.
What it catches
| Problem | What you see | |
|---|---|---|
Log path in a privacy-protected folder (~/Documents, ~/Desktop, ~/Downloads, iCloud Drive…) |
exit 78 (EX_CONFIG), no output at all. Jobs loaded before the change keep working until the next reboot, then break | auto-fix → ~/Library/Logs |
Split StartCalendarInterval: [{Minute: 55}, {Hour: 5}] instead of [{Hour: 5, Minute: 55}] |
runs every hour at :55 and every minute from 5:00–5:59: 84 runs/day | auto-fix (merge) |
Apple's Python on a protected folder (/usr/bin/python3, CommandLineTools) |
Operation not permitted, works in Terminal but never from launchd |
explains |
| Program / script missing or not executable | exit 127 / 126 | explains |
KeepAlive crash loop |
hundreds of restarts, job never stays up | explains |
| Non-zero last exit | decoded exit code | explains |
| Huge log files (>50 MB) | disk fills slowly | explains |
| Empty or unparseable plists | job silently ignored | explains |
Read the full story of the first bug: Why your LaunchAgent exits 78 with no output.
Circuit breaker for your own agents
A job that fails on every run wastes CPU and buries the real error in its log.
watch pauses it and retries later:
- 3 failed runs in a row (exit ≠ 0, not killed by a signal) →
launchctl bootout+ macOS notification - Half-open retry after 24 h, doubling every time it trips again (max 7 days); one good run closes the breaker
- exit 126/127 → notifies right away, since every run will fail the same way
launchd-doctor install-watch --prefix com.myname. # runs `watch` every 30 min
launchd-doctor breakers # what's paused, and when it retries
launchd-doctor resume com.myname.job # un-pause now
watch only touches agents matching --prefix, never Apple's or other vendors' agents.
Install
pip install git+https://github.com/naviidaviimusic/launchd-doctor
# or just grab the one file:
curl -O https://raw.githubusercontent.com/naviidaviimusic/launchd-doctor/main/launchd_doctor.py
python3 launchd_doctor.py
Commands
launchd-doctor [scan] [--prefix P] [-v] find problems (exit 1 if any)
launchd-doctor fix [--apply] [--prefix P] fix what can be fixed (dry run by default)
launchd-doctor watch --prefix P [--trip N] [--dry-run]
launchd-doctor install-watch --prefix P
launchd-doctor breakers
launchd-doctor resume LABEL
Why this exists
I run 100+ LaunchAgents for a local AI system on one Mac. Each of these bugs took it down at some point. The split-calendar bug sent 97 agents firing 83× a day and produced 49,000 duplicate events. The privacy-folder log path broke every agent that got reloaded, and none of them logged anything. This tool is what I wish I'd had.
License
MIT © Victor Navejar (Navii)
Metadata
Release files for launchd-doctor 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| launchd_doctor-0.1.0.tar.gz | 11.7 kB | With provenance | Details for launchd_doctor-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| launchd_doctor-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for launchd_doctor-0.1.0-py3-none-any.whl |
Total release size: 22.8 kB
Release files / launchd_doctor-0.1.0.tar.gz
| Download URL | launchd_doctor-0.1.0.tar.gz |
|---|---|
| Size | 11.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4c1be966b3d051d182226cedfd1adb3ed6170bc5513f993c8c0887d871fdffa1
|
|
BLAKE2b-256 checksum How to use checksums |
dfefe816587d2698d98403b3f1018ef3b04fcd43c5d8a338c211edeca6de7de4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.
Transparency logRelease files / launchd_doctor-0.1.0-py3-none-any.whl
| Download URL | launchd_doctor-0.1.0-py3-none-any.whl |
|---|---|
| Size | 11.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3fdb63de480a5b7b6d613b9e499d32a183625ee635a2b8dd1556f4b5aa6e7c09
|
|
BLAKE2b-256 checksum How to use checksums |
bdffb5e509d3d3025c390e0d0e1270c221fca46781051dbfbf39012a1af36f50
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.
Transparency logSecurity for launchd-doctor 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for launchd_doctor-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.