automating-mac-apps

Name: automating-mac-apps
Author: SpillwaveSolutions

130installs3forks

How to install automating-mac-apps?

spillwavesolutions/automating-mac-apps-plugin/automating-mac-apps

$npx -y skills add SpillwaveSolutions/automating-mac-apps-plugin --skill automating-mac-apps

Installs into the current project.

Summary

Automates macOS apps via Apple Events using AppleScript (discovery), JXA (legacy), and PyXA (modern Python). Use when asked to "automate Mac apps", "write AppleScript", "JXA scripting", "osascript automation", or "PyXA Python automation". Foundation skill for all macOS app automa

Files · 1

View on GitHub

SKILL.md

1	# Automating macOS Apps (Apple Events, AppleScript, JXA)
2
3	## Technology Status
4
5	JXA and AppleScript are legacy (last major updates: 2015-2016). Modern alternatives:
6	- PyXA: Active Python automation (see installation below)
7	- Shortcuts App: Visual workflow builder
8	- Swift/Objective-C: Production-ready automation
9
10	## macOS Sequoia 15 Notes
11
12	Test scripts on target macOS due to:
13	- Stricter TCC permissions
14	- Enhanced Apple Events security
15	- Sandbox improvements
16
17	## Core framing (use this mental model)
18	- Apple Events: The underlying inter-process communication (IPC) transport for macOS automation.
19	- AppleScript: The original DSL (Domain-Specific Language) for Apple Events: best for discovery, dictionaries, and quick prototypes.
20	- JXA (JavaScript for Automation): A JavaScript binding to the Apple Events layer: best for data handling, JSON, and maintainable logic.
21	- ObjC Bridge: JavaScript access to Objective-C frameworks (Foundation, AppKit) for advanced macOS capabilities beyond app dictionaries.
22
23	## When to use which
24	- Use AppleScript for discovery, dictionary exploration, UI scripting, and quick one-offs.
25	- Use JXA for robust logic, JSON pipelines, integration with Python/Node, and long-lived automation.
26	- Hybrid pattern (recommended): discover in AppleScript, implement in JXA for production use.
27
28	## When to use this skill
29	- Foundation for app-specific skills (Calendar, Notes, Mail, Keynote, Excel, Reminders).
30	- Run the automation warm-up scripts before first automation to surface macOS permission prompts.
31	- Use as the base reference for permissions, shell integration, and UI scripting fallbacks.
32
33	## Workflow (default)
34	1) Identify target app + dictionary using Script Editor.
35	2) Prototype a minimal command that works.
36	- Example: `tell application "Finder" to get name of first item in desktop`
37	3) Decide language using the rules above.
38	4) Harden: add error handling, timeouts, and permission checks.
39	- JXA: `try { ... } catch (e) { console.log('Error:', e.message); }`
40	- AppleScript: `try ... on error errMsg ... end try`
41	5) Validate: run a read-only command and check outputs.
42	- Example: `osascript -e 'tell application "Finder" to get name of home'`
43	- Confirm: Output matches expected (e.g., user home folder name)
44	6) Integrate via `osascript` for CLI or pipeline use.
45	7) UI scripting fallback only when the dictionary is missing/incomplete.
46	- Example UI Script: `tell application "System Events" to click button 1 of window 1 of process "App"`
47	- Example JXA: `Application('System Events').processes.byName('App').windows[0].buttons[0].click()`
48
49	## Validation Checklist
50	- [ ] Automation/Accessibility permissions granted (System Settings > Privacy & Security)
51	- [ ] App is running: `Application("App").running()` returns true
52	- [ ] State checked before acting (e.g., folder exists)
53	- [ ] Dictionary method used (not UI scripting)
54	- [ ] Delays/retries added for UI operations
55	- [ ] Read-only test command succeeds
56	- [ ] Output matches expected values
57
58	## Automation permission warm-up
59	- Use before first automation run or after macOS updates to surface prompts:
60	- All apps at once: `skills/automating-mac-apps/scripts/request_automation_permissions.sh` (or `.py`).
61	- Per-app: `skills/automating-<app>/scripts/set_up_<app>_automation.{sh,py}` (calendar, notes, mail, keynote, excel, reminders).
62	- Voice Memos (no dictionary): `skills/automating-voice-memos/scripts/set_up_voice_memos_automation.sh` to activate app + check data paths; enable Accessibility + consider Full Disk Access.
63	- Run from the same host you intend to automate with (Terminal vs Python) so the correct app gets Automation approval.
64	- Each script runs read-only AppleScript calls (list accounts/calendars/folders, etc.) to request Terminal/Python control; click “Allow” when prompted.
65
66	## Modern Python Alternatives to JXA
67
68	PyXA (Python for macOS Automation) - Preferred for new projects:
69
70	### PyXA Features
71	- Active development (v0.2.3+), modern Python syntax
72	- App automation: Safari, Calendar, Reminders, Mail, Music
73	- UI scripting, clipboard, notifications, AppleScript integration
74	- Method chaining: `app.lists().reminders().title()`
75
76	### PyXA Installation {#pyxa-installation}
77
78	```bash
79	# Install PyXA
80	pip install mac-pyxa
81
82	# Or with pip3 explicitly
83	pip3 install mac-pyxa
84
85	# Requirements:
86	# - Python 3.10+ (check with: python3 --version)
87	# - macOS 12+ (Monterey or later recommended)
88	# - PyObjC is installed automatically as a dependency
89
90	# Verify installation
91	python3 -c "import PyXA; print(f'PyXA {PyXA.__version_

People who liked this also viewed

6 picks

Type

automating-mac-apps

130installs3forks

View on GitHub

How to install automating-mac-apps?

spillwavesolutions/automating-mac-apps-plugin/automating-mac-apps

$npx -y skills add SpillwaveSolutions/automating-mac-apps-plugin --skill automating-mac-apps

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Automating macOS Apps (Apple Events, AppleScript, JXA)
2
3	## Technology Status
4
5	JXA and AppleScript are legacy (last major updates: 2015-2016). Modern alternatives:
6	- PyXA: Active Python automation (see installation below)
7	- Shortcuts App: Visual workflow builder
8	- Swift/Objective-C: Production-ready automation
9
10	## macOS Sequoia 15 Notes
11
12	Test scripts on target macOS due to:
13	- Stricter TCC permissions
14	- Enhanced Apple Events security
15	- Sandbox improvements
16
17	## Core framing (use this mental model)
18	- Apple Events: The underlying inter-process communication (IPC) transport for macOS automation.
19	- AppleScript: The original DSL (Domain-Specific Language) for Apple Events: best for discovery, dictionaries, and quick prototypes.
20	- JXA (JavaScript for Automation): A JavaScript binding to the Apple Events layer: best for data handling, JSON, and maintainable logic.
21	- ObjC Bridge: JavaScript access to Objective-C frameworks (Foundation, AppKit) for advanced macOS capabilities beyond app dictionaries.
22
23	## When to use which
24	- Use AppleScript for discovery, dictionary exploration, UI scripting, and quick one-offs.
25	- Use JXA for robust logic, JSON pipelines, integration with Python/Node, and long-lived automation.
26	- Hybrid pattern (recommended): discover in AppleScript, implement in JXA for production use.
27
28	## When to use this skill
29	- Foundation for app-specific skills (Calendar, Notes, Mail, Keynote, Excel, Reminders).
30	- Run the automation warm-up scripts before first automation to surface macOS permission prompts.
31	- Use as the base reference for permissions, shell integration, and UI scripting fallbacks.
32
33	## Workflow (default)
34	1) Identify target app + dictionary using Script Editor.
35	2) Prototype a minimal command that works.
36	- Example: `tell application "Finder" to get name of first item in desktop`
37	3) Decide language using the rules above.
38	4) Harden: add error handling, timeouts, and permission checks.
39	- JXA: `try { ... } catch (e) { console.log('Error:', e.message); }`
40	- AppleScript: `try ... on error errMsg ... end try`
41	5) Validate: run a read-only command and check outputs.
42	- Example: `osascript -e 'tell application "Finder" to get name of home'`
43	- Confirm: Output matches expected (e.g., user home folder name)
44	6) Integrate via `osascript` for CLI or pipeline use.
45	7) UI scripting fallback only when the dictionary is missing/incomplete.
46	- Example UI Script: `tell application "System Events" to click button 1 of window 1 of process "App"`
47	- Example JXA: `Application('System Events').processes.byName('App').windows[0].buttons[0].click()`
48
49	## Validation Checklist
50	- [ ] Automation/Accessibility permissions granted (System Settings > Privacy & Security)
51	- [ ] App is running: `Application("App").running()` returns true
52	- [ ] State checked before acting (e.g., folder exists)
53	- [ ] Dictionary method used (not UI scripting)
54	- [ ] Delays/retries added for UI operations
55	- [ ] Read-only test command succeeds
56	- [ ] Output matches expected values
57
58	## Automation permission warm-up
59	- Use before first automation run or after macOS updates to surface prompts:
60	- All apps at once: `skills/automating-mac-apps/scripts/request_automation_permissions.sh` (or `.py`).
61	- Per-app: `skills/automating-<app>/scripts/set_up_<app>_automation.{sh,py}` (calendar, notes, mail, keynote, excel, reminders).
62	- Voice Memos (no dictionary): `skills/automating-voice-memos/scripts/set_up_voice_memos_automation.sh` to activate app + check data paths; enable Accessibility + consider Full Disk Access.
63	- Run from the same host you intend to automate with (Terminal vs Python) so the correct app gets Automation approval.
64	- Each script runs read-only AppleScript calls (list accounts/calendars/folders, etc.) to request Terminal/Python control; click “Allow” when prompted.
65
66	## Modern Python Alternatives to JXA
67
68	PyXA (Python for macOS Automation) - Preferred for new projects:
69
70	### PyXA Features
71	- Active development (v0.2.3+), modern Python syntax
72	- App automation: Safari, Calendar, Reminders, Mail, Music
73	- UI scripting, clipboard, notifications, AppleScript integration
74	- Method chaining: `app.lists().reminders().title()`
75
76	### PyXA Installation {#pyxa-installation}
77
78	```bash
79	# Install PyXA
80	pip install mac-pyxa
81
82	# Or with pip3 explicitly
83	pip3 install mac-pyxa
84
85	# Requirements:
86	# - Python 3.10+ (check with: python3 --version)
87	# - macOS 12+ (Monterey or later recommended)
88	# - PyObjC is installed automatically as a dependency
89
90	# Verify installation
91	python3 -c "import PyXA; print(f'PyXA {PyXA.__version_

People who liked this also viewed

6 picks

Type