Skip to content
Skills Library
Programming · Automation

capture-screen

/capture-screen

Programmatic screenshot capture on macOS. Find window IDs with Swift CGWindowListCopyWindowInfo, control application windows via AppleScript (zoom, scroll, select), and capture with screencapture. Use when automating screenshots, capturing application windows for documentation, or building multi-shot visual workflows.

Licence
MIT
Last repository change
26.10.2026

Assessment and security

95/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content30 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/get_window_id.swift

What it does and when to use it

Programmatic screenshot capture on macOS. Find window IDs with Swift CGWindowListCopyWindowInfo, control application windows via AppleScript (zoom, scroll, select), and capture with screencapture. Use when automating screenshots, capturing application windows for documentation, or building multi-shot visual workflows.

Original author description

Programmatic screenshot capture on macOS. Find window IDs with Swift CGWindowListCopyWindowInfo, control application windows via AppleScript (zoom, scroll, select), and capture with screencapture. Use when automating screenshots, capturing application windows for documentation, or building multi-shot visual workflows.

How it works

  1. Select observation or foreground control
  2. Quick Start
  3. Step 1: Get Window ID (Swift)
  4. Step 2: Control Window (AppleScript, optional foreground work)
  5. Step 3: Capture (screencapture)
  6. Multi-Shot Workflow
  7. Failed Approaches (DO NOT USE)
  8. Permission Troubleshooting
  9. Supported Applications
Original SKILL.md headings · 291 lines, 1,465 words
SKILL.md preview
---
name: capture-screen
description: Programmatic screenshot capture on macOS. Find window IDs with Swift CGWindowListCopyWindowInfo, control application windows via AppleScript (zoom, scroll, select), and capture with screencapture. Use when automating screenshots, capturing application windows for documentation, or building multi-shot visual workflows.
---

# Capture Screen

Programmatic screenshot capture on macOS: find windows, control views, capture images.

## Select observation or foreground control

For an existing view, enumerate and capture the exact window without activating it.
Skip Step 2 when no view change is needed. A window image proves visible content in
that capture, not keyboard focus, input delivery or a successful business action.

Before opening/raising windows, scrolling, selecting, changing zoom or sending keys,
the executing agent checks user activity and other agents' ownership. Use a concrete
task handoff or an existing explicit idle-desktop authorization; under the latter,
coordinate exclusive access and proceed without asking again. Idle input alone is
not ownership. Busy/unknown occupancy or unexpected input stops foreground actions;
continue independent reads and do not restore old focus after human takeover.

Inspect the chosen tool's activation semantics. An app-targeted call or a shell job
running in the background does not prove it preserves focus. A failed capture does
not authorize raising the window, permission changes or switching tools around a
host refusal/GUI lock. Only request a handoff when existing authorization is absent.

## Quick Start

### Observe an unidentified dialog or the full desktop

Use this route when the user requests a whole-screen view, or when permitted
window observation cannot identify the reported obstruction. First establish
that the host permits this capture and its scope. An app-specific control
refusal does not prove screen capture is unavailable; it also does not authorize
using a different tool to read content the host protects. Stop if the refusal
covers the proposed capture or a GUI lock prevents it.

Capture without activation, scrolling or input:

```bash
capture_dir="$(mktemp -d)"
screencapture -x "$capture_dir/desktop.png"
```

Inspect the resulting image with the host's permitted image viewer. On a
multi-display desktop, inspect each produced display image before claiming to
have checked the whole desktop. File creation alone does not prove the requested
dialog was captured. Once identified, prefer the exact window for further
observations and keep the user's reported interaction failure in scope.

Follow the macOS permission owner's `macos-permissions` entry for classification
and recovery.

### Capture a known window

```bash
# Find Excel window ID
swift scripts/get_window_id.swift Excel

# Capture that window (replace 12345 with actual WID)
screencapture -x -l 12345 output.png
```

## Step 1: Get Window ID (Swift)

Use the bundled Swift/CoreGraphics route when the host permits window enumeration.
Prefer the host's native window inventory when it supplies the required IDs.

### Quick inline execution

```bash
swift -e '
import CoreGraphics
let keyword = "Excel"
let list = CGWindowListCopyWindowInfo(.optionOnScreenOnly, kCGNullWindowID) as? [[String: Any]] ?? []
for w in list {
    let owner = w[kCGWindowOwnerName as String] as? String ?? ""
    let name = w[kCGWindowName as String] as? String ?? ""
    let wid = w[kCGWindowNumber as String] as? Int ?? 0
    if owner.localizedCaseInsensitiveContains(keyword) || name.localizedCaseInsensitiveContains(keyword) {
        print("WID=\(wid) | App=\(owner) | Title=\(name)")
    }
}
'
```

### Using the bundled script

```bash
swift scripts/get_window_id.swift Excel
swift scripts/get_window_id.swift Chrome
swift scripts/get_window_id.swift          # List all windows
```

Output format: `WID=12345 | App=Microsoft Excel | Title=workbook.xlsx`

Parse the WID number for use with `screencapture -l`.

## Step 2: Control Window (AppleScript, optional foreground work)

Use these commands only inside the authorized foreground interval above. Bind the
exact app/window/document before using any `active window` or `active workbook`
example; never infer the target from whichever window happens to be active.

### Microsoft Excel (full AppleScript support)

```bash
# Activate (bring to front)
osascript -e 'tell application "Microsoft Excel" to activate'

# Set zoom level (percentage)
osascript -e 'tell application "Microsoft Excel"
    set zoom of active window to 120
end tell'

# Scroll to specific row
osascript -e 'tell application "Microsoft Excel"
    set scroll row of active window to 45
end tell'

# Scroll to specific column
osascript -e 'tell application "Microsoft Excel"
    set scroll column of active window to 3
end tell'

# Select a cell range
osascript -e 'tell application "Microsoft Excel"
    select range "A1" of active sheet
end tell'

# Select a specific sheet
osascript -e 'tell application "Microsoft Excel"
    activate object sheet "DCF" of active workbook
end tell'

# Open a file
osascript -e 'tell application "Microsoft Excel"
    open POSIX file "/path/to/file.xlsx"
end tell'
```

### Any application (basic control)

```bash
# Activate any app
osascript -e 'tell application "Google Chrome" to activate'

# Bring specific window to front (by index)
osascript -e 'tell application "System Events"
    tell process "Google Chrome"
        perform action "AXRaise" of window 1
    end tell
end tell'
```

### Timing and Timeout

Always add `sleep 1` after AppleScript commands before capturing, to allow UI rendering to complete.

**IMPORTANT**: `osascript` hangs indefinitely if the target application is not running or not responding. Always wrap with `timeout`:

```bash
timeout 5 osascript -e 'tell application "Microsoft Excel" to activate'
```

## Step 3: Capture (screencapture)

```bash
# Capture specific window by ID
screencapture -l <WID> output.png

# Silent capture (no camera shutter sound)
screencapture -x -l <WID> output.png

# Capture as JPEG
screencapture -l <WID> -t jpg output.jpg

# Capture with delay (seconds)
screencapture -l <WID> -T 2 output.png

# Capture a screen region (interactive)
screencapture -R x,y,width,height output.png
```

### Retina displays

On Retina Macs, `screencapture` outputs 2x resolution by default (e.g., a 2032x1238 window produces a 4064x2476 PNG). This is normal. To get 1x resolution, resize after capture:

```bash
sips --resampleWidth 2032 output.png --out output_1x.png
```

### Verify capture

```bash
# Check file was created and has content
ls -la output.png
file output.png    # Should show "PNG image data, ..."
```

## Multi-Shot Workflow

Foreground example: capture multiple sections of an Excel workbook. Establish the
authorization and exclusive ownership above first. If a user takes over, stop the
remaining sequence rather than replaying it or restoring your previous focus.

```bash
# 1. Open file and activate Excel
osascript -e 'tell application "Microsoft Excel"
    open POSIX file "/path/to/model.xlsx"
    activate
end tell'
sleep 2

# 2. Set up view
osascript -e 'tell application "Microsoft Excel"
    set zoom of active window to 130
    activate object sheet "Summary" of active workbook
end tell'
sleep 1

# 3. Get window ID
#    IMPORTANT: Always re-fetch before capturing. CGWindowID is invalidated
#    when an app restarts or a window is closed and reopened.
WID=$(swift -e '
import CoreGraphics
let list = CGWindowListCopyWindowInfo(.optionOnScreenOnly, kCGNullWindowID) as? [[String: Any]] ?? []
for w in list {
    let owner = w[kCGWindowOwnerName as String] as? String ?? ""
    let wid = w[kCGWindowNumber as String] as? Int ?? 0
    if owner == "Microsoft Excel" { print(wid); break }
}
')
echo "Window ID: $WID"

# 4. Capture Section A (top of sheet)
osascript -e 'tell application "Microsoft Excel"
    set scroll row of active window to 1
end tell'
sleep 1
screencapture -x -l $WID section_a.png

# 5. Capture Section B (further down)
osascript -e 'tell application "Microsoft Excel"
    set scroll row of active window to 45
end tell'
sleep 1
screencapture -x -l $WID section_b.png

# 6. Switch sheet and capture
osascript -e 'tell application "Microsoft Excel"
    activate object sheet "DCF" of active workbook
    set scroll row of active window to 1
end tell'
sleep 1
screencapture -x -l $WID dcf_overview.png
```

## Failed Approaches (DO NOT USE)

These methods were tested and confirmed to fail on macOS:

| Method | Error | Why It Fails |
|--------|-------|-------------|
| `System Events` → `id of window` | Error -1728 | System Events cannot access window IDs in the format screencapture needs |
| Python `import Quartz` (PyObjC) | `ModuleNotFoundError` | PyObjC not installed in system Python; don't attempt to install it — use Swift instead |
| `osascript` window id | Wrong format | Returns AppleScript window index, not CGWindowID needed by `screencapture -l` |

## Permission Troubleshooting

If `get_window_id.swift` cannot enumerate windows or a required field is unavailable,
read the actual result before attributing the failure to Screen Recording. Request
the helper's diagnostic guidance without enumerating windows:

```bash
swift scripts/get_window_id.swift --permission-hint screen
swift scripts/get_window_id.swift --permission-hint microphone
```

Interpret that output with the [helper diagnostic procedure](references/permission-triage-template.md).
The hint prints guidance and execution context; it does not check grant state or
identify which process should receive a grant. Keep general TCC attribution,
permission changes and request recovery with `macos-permissions`.

## Supported Applications

| Application | Window ID | AppleScript Control | Notes |
|------------|-----------|-------------------|-------|
| Microsoft Excel | Swift | Full (zoom, scroll, select, activate sheet) | Best supported |
| Google Chrome | Swift | Basic (activate, window management) | No scroll/zoom via AppleScript |
| Other macOS apps | Swift or permitted host inventory | App-dependent | Capture requires host permission and a capturable surface |

AppleScript control depth varies by application. Excel has the richest AppleScript dictionary. For apps with limited AppleScript, keyboard simulation via `System Events` is a foreground alternative only after the entry gate passes, not an automatic recovery from a failed background action.
Files in this package (3)
  • SKILL.md 10 KB
  • references/permission-triage-template.md 2 KB
  • scripts/get_window_id.swift 9 KB

Versions

The database has no other skills named capture-screen.

Database snapshot: 13.11.2026 · package version a5cac1b0bb12 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100screencapture-mac
    Captures the user's macOS screen, a window, or a region with the built-in `screencapture` CLI, then reads the image so the agent can see what the user sees. Use it when the user asks to check how a native macOS app looks (SwiftUI, AppKit, Electron, Qt, Tk, Java Swing), verify a…
  • 100screencapture
    Captures the user's macOS screen, a window, or a region with the built-in `screencapture` CLI, then reads the image so the agent can see what the user sees. Use it when the user asks to check how a native macOS app looks (SwiftUI, AppKit, Electron, Qt, Tk, Java Swing), verify a…
  • 100macos-control
    Control macOS GUI applications via mouse automation, keyboard input, screenshots, image recognition, and AppleScript execution. Use when you need to interact with macOS app UIs, take screenshots, click buttons, type text, scroll, drag, or locate images on screen.
  • 90capture-screenshots
    Capture screenshots of each state, size and setting as evidence for a PR. Use for each UI change.
  • 100build-licenseseat-swift
    Use if integrating the LicenseSeat Swift SDK into a macOS/Swift app — activation, validation, seats.
  • 100xcode-preview-capture
    Build and capture SwiftUI previews for visual analysis in Codex. Use when asked to preview a Swift file, capture simulator UI, or inspect visual output from SwiftUI views.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.