A collection of custom macOS LaunchAgents, LaunchDaemons, and supporting scripts for automating tasks.
If you are unfamiliar with launchd jobs, they are part of macOS's unified service management framework. launchd is the system’s init process, responsible for starting, stopping, and managing jobs — including system daemons, user agents, applications, and scripts — based on configuration and triggers.
If you are interested in learning more about launchd, daemons, agents, and related tools, check out the Additional Resources section of this document.
Table of Contents
Below is a brief overview of the repository's directory structure, to help you understand its organization:
custom-daemon-agents/
├── agent-scripts/ # AppleScript and shell scripts executed by launchd jobs
└── launch-agents/ # LaunchAgent plist files
The table below lists the LaunchAgents, LaunchDaemons, and their associated scripts in this repository:
launchd Job |
Associated Script | Type | Description |
|---|---|---|---|
local.StrangeRanger.LogitechMonitor |
logitech-monitor.scpt |
LaunchAgent | Opens Logitech G Hub when a Logitech USB device (Vendor ID 0x046d) is detected. |
local.StrangeRanger.MouseMonitor |
mouse-monitor.scpt |
LaunchAgent | Opens LinearMouse when the configured mouse (by Product ID) is detected. |
These LaunchAgents start automatically upon login, running scripts within your user context.
- Create a directory for the scripts, then copy them into it:
mkdir -p ~/.agent-scripts/ cp agent-scripts/* ~/.agent-scripts/
- Copy the
.plistfiles to~/Library/LaunchAgents/:cp launch-agents/* ~/Library/LaunchAgents/
- Replace
hunterwith your username in the.plistfiles:sed -i '' -e 's/\/Users\/hunter/\/Users\/YOUR_USERNAME/' ~/Library/LaunchAgents/PLIST_FILE.plist
- Load and start the agent(s):
- Modern (recommended on recent macOS versions):
# Load the job launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/<plist> # Enable the job launchctl enable gui/$(id -u)/<Label> # (Re)start the job launchctl kickstart -k gui/$(id -u)/<Label>
- Legacy (still works):
launchctl load ~/Library/LaunchAgents/<plist>
- Modern (recommended on recent macOS versions):
Note
- If you used a directory other than
~/.agent-scripts/, update theProgramArgumentspath(s) in the.plistfile(s).
Currently, this repository does not contain any LaunchDaemons.
| macOS Version | Status | Notes |
|---|---|---|
| macOS 26 | Supported | N/A |
| ≤ macOS 15 | Unsupported | SPUSBDataType isn't available in macOS 26 and later. Use branch 15 instead. |
The agent is not listed or didn’t start — how can I check status?
Use this to see if the job is loaded in your user domain:
launchctl list | grep StrangeRangerIf it’s not listed, load it using the steps in “How to Use.”
How can I inspect details for a specific agent?
Print the runtime state and last exit status:
launchctl print gui/$(id -u)/local.StrangeRanger.MouseMonitor launchctl print gui/$(id -u)/local.StrangeRanger.LogitechMonitor
How do I unload, disable, or restart an agent?
Modern commands:
# Stop/unload launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/<plist> # Disable so it won’t auto-start launchctl disable gui/$(id -u)/<Label> # (Re)start immediately launchctl kickstart -k gui/$(id -u)/<Label>Legacy alternative:
launchctl unload ~/Library/LaunchAgents/<plist> launchctl load ~/Library/LaunchAgents/<plist>
Why am I seeing AppleScript alerts from these agents?
On fatal errors, the scripts show an AppleScript alert and then unloads the agent to avoid retry loops. Because they run as LaunchAgents (in your user session), alerts are allowed. If you prefer non‑interactive behavior, remove the alert from the script(s) and log the error instead.
How do I find my device IDs (Vendor ID and Product ID)?
List connected USB devices and filter for IDs:
system_profiler SPUSBHostDataType | grep -E "(Vendor ID|Product ID|Manufacturer)"Look for lines such as:
Vendor ID: 0x1234 Product ID: 0xabcdUse those values to set the
vendorIDand/orproduct IDvariables in the AppleScript(s) for your specific hardware.
- Man pages:
man launchctl,man launchd.plist - Apple documentation:
- Third party tools/info:
- LaunchControl (tool)
- What is launchd? (info)
Please use GitHub Issues for bug reports.
This project is licensed under the MIT License.