Use Shortcuts (over KM or BTT) when:

• The automation needs to run on iPhone or iPad
• It needs a Siri voice trigger
• It appears in the share sheet (e.g., process selected text/files from any app)
• It involves Apple-specific services (Health, HomeKit, Focus modes, Messages)

From terminal:

shortcuts run "Shortcut Name"

From Keyboard Maestro: Use the “Execute Shell Script” action with the shortcuts run command.

From Hammerspoon:

hs.task.new("/usr/bin/shortcuts", nil, {"run", "Shortcut Name"}):start()

Named triggers let other apps (Keyboard Maestro, Hammerspoon, scripts) fire BTT actions by name via URL scheme or AppleScript.

Calling a named trigger:

open "btt://trigger_named/?trigger_name=YOUR_TRIGGER_NAME"

From Keyboard Maestro: Use the “Open URL” action with the btt:// URL scheme.

From Hammerspoon:

hs.urlevent.openURL("btt://trigger_named/?trigger_name=YOUR_TRIGGER_NAME")

Window snapping zones are defined in BTT → Window Snapping & Moving. Drag a window to a screen edge or corner to snap it to a predefined layout.

Stream Deck is configured inside BTT (not the Elgato app). Actions are organized into profiles per application context.

• BTT → Stream Deck tab → configure buttons, folders, and dynamic content
• Use BTT named triggers to call complex multi-tool actions from Stream Deck buttons

BTT config is stored in ~/Library/Application Support/BetterTouchTool/. Back up before updates. Cloud sync is available in BTT settings if enabled.

Export a snapshot: BTT → Manage Presets → Export.

HammerFlow manages Hammerspoon hotkey bindings in TOML configuration files, making them readable and maintainable without editing raw Lua.

Config location: ~/.hammerspoon/hammerflow.toml (or similar — check init.lua for exact path)

Format:

[[bindings]]
key = "h"
mods = ["ctrl", "alt"]
action = "some_action"
description = "Do something"

Spoons are Hammerspoon plugins stored in ~/.hammerspoon/Spoons/. List installed:

ls ~/.hammerspoon/Spoons/

Common useful Spoons: MiroWindowsManager (window grid), ReloadConfiguration (auto-reload on save), SpoonInstall (install other Spoons).

Hammerspoon can call BTT named triggers and vice versa:

Hammerspoon → BTT:

hs.urlevent.openURL("btt://trigger_named/?trigger_name=TRIGGER_NAME")

Reload config:

hs.reload()

Or use the menu bar Hammerspoon icon → Reload Config.

Open the Hammerspoon console from the menu bar icon to see print output and errors. Add print("debug message") anywhere in Lua for tracing.

Watch the console when reloading config — syntax errors appear immediately.

Palettes are visual popup menus of macros triggered by a hotkey. Use them to group related macros without memorizing individual shortcuts.

Create: New Group → set “Show as palette when…” → assign a trigger hotkey.

KM variables persist across macro runs. Use Set Variable action and reference with %Variable%VariableName%.

The Named Clipboard system stores multiple clipboard items — useful for multi-step copy-paste workflows across windows.

Macros are stored in ~/Library/Application Support/Keyboard Maestro/Keyboard Maestro Macros.plist. Sync via iCloud Drive or back up manually before major changes.

Export groups: right-click group → Export → saves as .kmmacros file.

Script commands live in a directory registered in Raycast → Preferences → Extensions → Script Commands. Add a directory and Raycast will scan it for scripts with the required comment headers.

Typical location: ~/Scripts/raycast/ or ~/Developer/raycast-scripts/

Every script needs a header block:

#!/bin/bash
# @raycast.schemaVersion 1
# @raycast.title My Script
# @raycast.mode compact
# @raycast.packageName My Scripts
# @raycast.description Does something useful

echo "Result shown in Raycast"

Modes:

• compact — result shown inline in Raycast
• fullOutput — opens a dedicated output window
• silent — no output shown

# @raycast.argument1 { "type": "text", "placeholder": "Enter value" }

echo "You entered: $1"

Raycast prompts for the argument before running.

BTT owns gesture input — trackpad gestures, mouse button remapping, keyboard sequences, and named triggers that other tools can call. Window snapping zones are set here. The Stream Deck is configured here.

Keyboard Maestro owns complex logic — anything requiring conditionals, variables, loops, or multi-step clipboard manipulation. Palette menus for triggering groups of macros live here.

Hammerspoon is the programmable fallback — when BTT or KM can’t do something (usually low-level window or system manipulation), Lua handles it. HammerFlow manages the hotkey config in TOML.

Raycast handles daily launcher use — switching apps, snippets, clipboard history, quick calculations, and file search. Scripts here are single-purpose utilities.

Shortcuts handles anything that needs to cross devices or appear in the Siri/share sheet context.