Skip to main content

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)

Source distribution for launchd-doctor 0.1.0
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)

Table of built distributions (wheels) for launchd-doctor 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page