Hi everyone,
I wanted a visible reminder when a Keyboard Maestro macro keeps running longer than expected—for example, when it is waiting for a condition or a dialog I have overlooked.
With help from Codex, I put together Keyboard Maestro Watchdog. I’m sharing the source in case others find it useful or have suggestions for improving it.
It runs as a separate macOS background helper. There is no .kmmacros file to import, and no monitoring loop needs to be added to individual macros.
Example alert
Example banner rendered from the helper’s AppKit view, using a sample macro name.
What it does
- Checks running macro instances approximately once per second.
- Shows a silent, persistent banner when an execution has been observed running for at least 30 seconds.
- Displays the execution’s name without making the banner the active application.
- Keeps the banner visible until I close it, even if the macro has since finished.
- Suppresses repeated alerts for the same macro name while matching executions remain active.
- Supports optional UUID exemptions for macros that are expected to run for a long time.
It does not cancel macros or restart Keyboard Maestro Engine.
How it works
A Python observer queries the Engine through AppleScript using %ExecutingInstances%, tracks how long each instance has been visible, and uses %ExecutingInstanceName%instance% to get the name. A small Swift/AppKit helper displays the alert. A user LaunchAgent starts the observer at login.
A few limitations
This is a long-running-macro reminder. It does not detect an actual Keyboard Maestro action timeout or prove that a macro has become stuck. Intentional pauses and prompts count toward the threshold too.
Timing starts at first observation, and restarting the helper resets it. Names generally identify the parent execution, so the alert may not identify a particular nested action. Suppression is by name, so separate macros with identical names are grouped together.
It also depends on the Engine answering AppleScript requests. If the Engine becomes unresponsive, the helper logs the failed check; it does not display a separate Engine-freeze alert.
Download and setup
Keyboard-Maestro-Watchdog.zip (8.7 KB)
The ZIP contains the Python and Swift source, an installer, tracker checks, and a README with installation, configuration, troubleshooting, and removal instructions. It requires Python 3 and Apple’s command-line developer tools to build the banner. macOS may request Automation permission to query Keyboard Maestro Engine.
After extracting the ZIP, open Terminal in its Keyboard-Maestro-Watchdog folder and run:
python3 install.py --check
python3 test_tracker.py
python3 install.py
The last command installs and starts the helper for the current user. It refuses to overwrite an existing installation. No administrator privileges are needed.
The original helper is running on my Mac with Keyboard Maestro 11. This source edition has passed local syntax, build, and tracker checks, but has not been tested on a clean second Mac. My personal macro exemption has been removed from the shared copy.
I’d welcome feedback—especially on instance tracking, duplicate-name handling, and whether there is a simpler native approach to this kind of persistent reminder.