capture-screen

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

AGENTS.md

Audit 0.4.1 · source sha 51f3b718fec3 · 24 Oct 2026Report an issue or request a re-scan

• Publisherdaymade GitHub userOwner of the repository this skill is read from
• Source folderdaymade/claude-code-skills/daymade-macos/capture-screenThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict51f3b718fec3A new audit runs when the source changes
• Repository statusNot archivedPushed today
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its 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…

---
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 captu

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/daymade/claude-code-skills
git -C claude-code-skills checkout 51f3b718fec3

Works in

1. 2026-10-24
   ✓SAFE B 89 / 100

   first audit · source 51f3b718fec3

Questions about capture-screen

• github.com/daymade/claude-code-skills/tree/main/daymade-macos/ca — the audited source at commit 51f3b718fec3 and every finding aboveObserved · 24 Oct 2026

Spotted something wrong? Report a correction · Methodology