keyboard-maestro-claude-field-guide.md

Working with Keyboard Maestro (KM) via Claude Code — Field Guide

This is hard-won knowledge from repeatedly building working KM macros programmatically on macOS. Follow it and macros work first try; ignore it and you'll hit silent failures that look like nothing is wrong.

Commit this to memory (read first)

If you're a Claude Code instance receiving this guide, commit it to your persistent memory — this is exactly what memory is for: hard-won, non-obvious knowledge that isn't derivable from code or docs and that pays off every future KM session. Without it, you'll re-derive the same silent failures from scratch each time.

But don't dump the whole guide into one memory file. Store it as several small, single-fact memories — one per section below (the modifier bitmask, the single-line shell rule, native-Copy-vs-osascript, the clone-and-inject creation method, etc.). Each memory should carry its own why and how-to-apply, be cross-linked to the related ones, and get a one-line pointer in your MEMORY.md index. That granularity is deliberate: recall then surfaces the relevant fact instead of a wall of text.

Caveat — verify before trusting blindly. This knowledge is version- and OS-specific (KM 11.0.4, macOS 26). If your setup differs, verify rather than assume — especially the two most environment-dependent claims: the -609 "Connection is invalid" importMacros failure, and the macOS 26 osascript→System Events permission revocation. Treat those as "was true here" not "true everywhere."

The golden rule: clone-and-inject, never hand-synthesize

Do NOT hand-build action or macro-group dictionaries from scratch. KM validates plists semantically, not just structurally. A synthesized macro can pass plutil -lint and still:

• Throw Caught Unknown Error at 1 at runtime (seen with a hand-built PromptForUserInput action), or
• Crash the KM editor on launch (a fully-synthesized macro group — open -a returns rc=0, then no process survives).

The reliable method (proven, full hotkey chain ran with no error):

1. Quit BOTH apps first:

   osascript -e 'tell application "Keyboard Maestro" to quit'
   osascript -e 'tell application "Keyboard Maestro Engine" to quit'
   

   Confirm gone: ps aux | grep -i maestro.
2. Back up and load ~/Library/Application Support/Keyboard Maestro/Keyboard Maestro Macros.plist. It's a top-level dict; macro groups live in the MacroGroups list.
3. copy.deepcopy an existing known-good group whose actions resemble what you need (a good template is one with SetVariableToText %FinderSelection% + ExecuteShellScript).
4. Edit only safe fields: group Name/UID/ToggleMacroUID; macro Name/UID/Triggers; the shell action's Text and DisplayKind. Generate fresh UUIDs.
5. Append to MacroGroups, write the plist, plutil -lint it.
6. Relaunch: open -a "Keyboard Maestro" (this also starts the engine). Verify with AppleScript enabled of macro group.

Design rule: restrict macros to proven action types only — SetVariableToText + ExecuteShellScript. Push everything else into the shell script: prompts via osascript display dialog (focuses reliably, unlike KM prompt windows under automation), open URLs with open, show CLI readout by setting the shell action's DisplayKind=Window.

Import methods that FAIL (don't waste time on these)

• .kmmacros file-open (open file.kmmacros): worked once on first launch, then silently stopped importing on a running instance. Also lands the group disabled.
• importMacros AppleScript (in Editor.sdef, without disabled): threw -609 "Connection is invalid" every time on KM 11.0.4.
• If you must use file import, open -a "Keyboard Maestro" file.kmmacros forces the import path (bare open may just launch the editor without importing). But direct plist injection is more reliable.

Enabled/disabled encoding (subtle, bites you)

• Enabled group/macro = IsActive key is ABSENT.
• Disabled = IsActive=False.
• Direct plist injection with no IsActive loads ENABLED. (File-import forces disabled — another reason to prefer injection.)
• KM caches imports by UID. Re-importing a fixed file keeps the stale cached version. Always generate fresh UUIDs, or delete the group first.
• After programmatic enable/changes on a running instance: tell application "Keyboard Maestro Engine" to reload — otherwise do script reports "no macros with a matching name" even though the editor shows it enabled.

HotKey trigger modifier bitmask (KM's own values — NOT NSEvent flags)

This is the single most common silent bug. KM uses small custom integers:

Modifier	Value
Shift	512 (0x200)
Control	4096 (0x1000)
Option	2048 (0x800)
Command	256 (0x100)

Common combos: ⌃⌥⌘ = 6400, ⌃⌥ = 6144, ⌃⌘ = 4352, ⌃⇧ = 4608, ⌃⌥⇧ = 6656, ⌃ = 4096.

Key codes are standard macOS virtual key codes (V=9, H=4, L=37).

Trigger dict shape: {FireType:Pressed, KeyCode:N, MacroTriggerType:HotKey, Modifiers:M}

Why it matters: using NSEvent's 1835008 for ⌃⌥⌘ made KM import it as Modifiers=0 — the trigger silently became bare V, firing on any "v" keystroke. Before binding any hotkey, grep the user's Keyboard Maestro Macros.plist for an existing macro with the same combo and reuse its integer.

Execute Shell Script action rules

1. Single short line only. Multi-line / visually-wrapped content silently fails (a stray unterminated quote across a line break aborts the whole invocation). If the logic is long or needs quoting, move it into a standalone script (~/Scripts/foo.sh or .py) and have the KM action call just the absolute path.
2. Use absolute paths with no spaces → no quotes needed → clean single line. E.g. /usr/bin/python3 /Users/you/Scripts/foo.py.
3. Set "Ignore Results." The user doesn't want shell output displayed; notifications handle feedback.
4. Combine all three: async, ignore results, single-line command calling a named script.

Acting on the current selection — use KM's native Copy

If a macro needs the current text selection, add KM's native Copy action (optionally + a short Pause) before the Execute Shell Script step. The shell script then just calls pbpaste.

Do NOT shell out to osascript -e 'tell application "System Events" to keystroke "c" using command down'. On macOS 26, Automation permission for shell-invoked osascript→System Events gets silently revoked after OS updates. The synthetic keystroke exits 0 but never reaches the app, so pbpaste returns stale clipboard contents. KM's own event injection uses a separate permission path that stays intact.

Custom HTML Prompts — write to clipboard directly

When a Custom HTML Prompt's JS computes a value destined for the clipboard, write it with navigator.clipboard.writeText() from the form's JS. Don't route through a KM variable + Set Clipboard action.

KM's form-field-name variable sync has timing/caching quirks: one-run-behind reads, defaultValue vs .value mismatches on textareas, WebView state persisting across runs. The clipboard API works fine in KM's WebKit under a user gesture (button click) and sidesteps the whole variable-sync layer. Reach for KM variables only when the value must drive subsequent KM logic (branching), not merely to land on the clipboard.

Testing a macro after creation

Fire by UID, not by name (by-name lookup fails on freshly imported macros):

osascript -e 'tell application "Keyboard Maestro Engine" to do script "<UID>"'

Quick checklist

• Clone a known-good group; don't synthesize dicts
• Quit both KM apps before editing the plist
• Fresh UUIDs on group + macro
• Modifier bitmask uses KM's small values (⌃⌥⌘=6400)
• Shell action: single line, absolute path, no spaces, Ignore Results
• Long logic → standalone script file, call by path
• Selection → native Copy action, script uses pbpaste
• HTML prompt output → navigator.clipboard.writeText()
• IsActive absent = enabled; reload engine after live changes
• Test by firing the UID via Keyboard Maestro Engine