osascript-ui

name	osascript-ui
description	Automate native macOS app UIs via System Events Accessibility API. Use when traversing UI element trees, clicking buttons by label, reading text field values, or listing menu bar items. Does NOT work on Electron apps (Slack, VSCode, Chrome).

osascript-ui

System Events Accessibility API — UI automation for native AppKit apps. All scripts are Python with JXA embedded.

Critical Limitation

Only native AppKit apps expose full UI trees. Electron apps (Slack, VSCode, Chrome, Notion) only expose window chrome — not page content.

Menu bars work on ALL apps including Electron — menus are always accessible.

Requires: kTCCServiceAccessibility — System Settings > Privacy & Security > Accessibility

What's Accessible

Element	AX Role	Read via
Button	AXButton	.title() / .description()
Text field	AXTextField	.value()
Static text	AXStaticText	.value()
Checkbox	AXCheckBox	.value() (0/1)
Window	AXWindow	.name()
Menu bar	AXMenuBar	.menuBarItems()

Scripts

Dump the accessibility element tree for a named app (depth-limited):

uv run scripts/ui-tree.py "TextEdit"
uv run scripts/ui-tree.py "Finder" --depth 3

List all menu bar items and submenu items for any running app:

uv run scripts/menu-items.py "Safari"
uv run scripts/menu-items.py "Finder" --menu "File"

Click a UI element by role and label in a named app:

uv run scripts/ui-click.py "TextEdit" AXButton "Save"
uv run scripts/ui-click.py "System Preferences" AXCheckBox "Dark Mode"

Reference

• reference/05-system-events.md — Full UI element API, process list, window inspection, focus
• reference/15-limitations-and-gotchas.md — Electron blind spots, Accessibility limitations