automating-mac-apps

Automating macOS Apps (Apple Events, AppleScript, JXA)

Technology Status

JXA and AppleScript are legacy (last major updates: 2015-2016). Modern alternatives:

• PyXA: Active Python automation (see installation below)
• Shortcuts App: Visual workflow builder
• Swift/Objective-C: Production-ready automation

macOS Sequoia 15 Notes

Test scripts on target macOS due to:

• Stricter TCC permissions
• Enhanced Apple Events security
• Sandbox improvements

Core framing (use this mental model)

• Apple Events: The underlying inter-process communication (IPC) transport for macOS automation.
• AppleScript: The original DSL (Domain-Specific Language) for Apple Events: best for discovery, dictionaries, and quick prototypes.
• JXA (JavaScript for Automation): A JavaScript binding to the Apple Events layer: best for data handling, JSON, and maintainable logic.
• ObjC Bridge: JavaScript access to Objective-C frameworks (Foundation, AppKit) for advanced macOS capabilities beyond app dictionaries.

When to use which

• Use AppleScript for discovery, dictionary exploration, UI scripting, and quick one-offs.
• Use JXA for robust logic, JSON pipelines, integration with Python/Node, and long-lived automation.
• Hybrid pattern (recommended): discover in AppleScript, implement in JXA for production use.

When to use this skill

• Foundation for app-specific skills (Calendar, Notes, Mail, Keynote, Excel, Reminders).
• Run the automation warm-up scripts before first automation to surface macOS permission prompts.
• Use as the base reference for permissions, shell integration, and UI scripting fallbacks.

Workflow (default)

1. Identify target app + dictionary using Script Editor.
2. Prototype a minimal command that works.
   • Example: tell application "Finder" to get name of first item in desktop
3. Decide language using the rules above.
4. Harden: add error handling, timeouts, and permission checks.
   • JXA: try { ... } catch (e) { console.log('Error:', e.message); }
   • AppleScript: try ... on error errMsg ... end try
5. Validate: run a read-only command and check outputs.
   • Example: osascript -e 'tell application "Finder" to get name of home'
   • Confirm: Output matches expected (e.g., user home folder name)
6. Integrate via osascript for CLI or pipeline use.
7. UI scripting fallback only when the dictionary is missing/incomplete.
   • Example UI Script: tell application "System Events" to click button 1 of window 1 of process "App"
   • Example JXA: Application('System Events').processes.byName('App').windows[0].buttons[0].click()