| name | osascript-system |
| description | Inspect macOS system state with osascript/JXA. Use when listing running apps, enumerating windows with positions and IDs, taking targeted screenshots by window, querying display geometry, or using the ObjC bridge (NSWorkspace, CGWindow, NSFileManager). |
osascript-system
System state inspection via JXA + ObjC bridge. All scripts are Python with JXA embedded.
Critical Rule
Every ObjC call returns a wrapped object. Always ObjC.unwrap() before using in JS. This is the #1 error source.
Scripts
List all running apps via NSWorkspace (includes background daemons):
uv run scripts/list-apps.py
List all on-screen windows with bounds, layer, and CGWindow ID:
uv run scripts/list-windows.py
Screenshot a named app's window by CGWindow ID (no region math needed):
uv run scripts/screenshot-window.py "Safari"
uv run scripts/screenshot-window.py "Finder" /tmp/finder.png
Get the frontmost app: name, bundle ID, PID, and window title:
uv run scripts/get-focused-app.py
List all displays with frame, visible frame, and backing scale factor (Retina):
uv run scripts/get-displays.py
Screenshot a specific x,y,width,height pixel region of the screen:
uv run scripts/region-screenshot.py 0 0 1920 1080
uv run scripts/region-screenshot.py 100 100 800 600 /tmp/region.png
Key APIs
| Need | API |
|---|
| All running apps + PIDs | NSWorkspace.sharedWorkspace.runningApplications |
| All windows + positions + IDs | CGWindowListCopyWindowInfo |
| Screenshot specific window | CGWindow ID + screencapture -l |
| Currently focused app + window title | NSWorkspace.frontmostApplication + System Events |
| Display geometry, Retina scale | NSScreen.screens |
| Region screenshot by coordinates | screencapture -R x,y,w,h |
Reference
- reference/03-jxa-objc-bridge.md — NSFileManager, NSWorkspace, ObjC.unwrap() rule
- reference/04-system-capabilities.md — Shell bridge, clipboard, screen capture, polling
- reference/05-system-events.md — Process list, window inspection, UI tree, focus, login items
- reference/18-coregraphics-cgwindow.md — CGWindowListCopyWindowInfo, window IDs, z-order, display geometry
Permission Required
Screenshots require kTCCServiceScreenCapture. UI control via System Events requires kTCCServiceAccessibility.
