# Osascript System

> 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).

- Skill: `damionrashford/osascript-system` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add damionrashford/osascript-system`
- Raw SKILL.md: https://api.skillmd.com/api/skills/damionrashford/osascript-system/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: damionrashford (https://skillmd.com/u/damionrashford)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/damionrashford/osascript-system

---


# 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):
```bash
uv run scripts/list-apps.py
```

List all on-screen windows with bounds, layer, and CGWindow ID:
```bash
uv run scripts/list-windows.py
```

Screenshot a named app's window by CGWindow ID (no region math needed):
```bash
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:
```bash
uv run scripts/get-focused-app.py
```

List all displays with frame, visible frame, and backing scale factor (Retina):
```bash
uv run scripts/get-displays.py
```

Screenshot a specific x,y,width,height pixel region of the screen:
```bash
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](reference/03-jxa-objc-bridge.md) — NSFileManager, NSWorkspace, ObjC.unwrap() rule
- [reference/04-system-capabilities.md](reference/04-system-capabilities.md) — Shell bridge, clipboard, screen capture, polling
- [reference/05-system-events.md](reference/05-system-events.md) — Process list, window inspection, UI tree, focus, login items
- [reference/18-coregraphics-cgwindow.md](reference/18-coregraphics-cgwindow.md) — CGWindowListCopyWindowInfo, window IDs, z-order, display geometry

## Permission Required

Screenshots require `kTCCServiceScreenCapture`. UI control via System Events requires `kTCCServiceAccessibility`.