Find, activate, and screenshot macOS windows across Spaces. Use when you need to list windows, activate a specific window, take screenshots, filter windows by app name, title, process path, or command line, automate window workflows, or distinguish between production and sandbox/dev instances (e.g., JetBrains IDEs).
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Find, activate, and screenshot macOS windows across Spaces. Use when you need to list windows, activate a specific window, take screenshots, filter windows by app name, title, process path, or command line, automate window workflows, or distinguish between production and sandbox/dev instances (e.g., JetBrains IDEs).
Find, activate, and screenshot macOS windows across Spaces. Supports filtering by application name, window title (regex), process path, and command line arguments.
Quick Start
# List ALL windows
/window-controller list
# Find windows by app name (partial match)
/window-controller find "GoLand"# Find windows by title pattern (regex)
/window-controller find --title "research.*"# Activate window (switches to its Space)
/window-controller activate "GoLand"
/window-controller screenshot
/window-controller find --json
# Take screenshot of window (saves to artifacts by default)
"GoLand"
# Get window info as JSON (for automation)
"GoLand"
Filtering Options
By Application Name
# Partial match on kCGWindowOwnerName
/window-controller --find "GoLand"
/window-controller --find "Chrome"
By Window Title (Regex)
# Match window title with regex
/window-controller --find --title "monokai-islands"
/window-controller --find --title ".*\.py$"
/window-controller --find "GoLand" --title "research"
# Filter by process command line
/window-controller find "Main" --args-contains "idea.plugin.in.sandbox.mode"
By PID
# Find window by specific process ID
/window-controller find --pid 12345
JetBrains Sandbox IDEs
JetBrains sandbox IDEs (launched via ./gradlew runIde) have a key difference:
Sandbox IDEs appear as "Main" (Java process name), NOT "GoLand" or "IntelliJ IDEA"!
# Find sandbox IDE (reliable method)
/window-controller find "Main" --args-contains "idea.plugin.in.sandbox.mode"# Find by Gradle cache path
/window-controller find "Main" --path-contains ".gradle/caches"# Find by project name in title
/window-controller find "Main" --title "my-project"
How It Works
Window Detection
Uses CGWindowListCopyWindowInfo with kCGWindowListOptionAll to list ALL windows including:
Off-screen windows
Windows on other Spaces
Hidden/minimized windows
Process Information
Uses psutil to get detailed process information:
Executable path (exe())
Command line arguments (cmdline())
Space Detection
Parses the macOS Spaces configuration plist to map windows to Space indexes and identify which Space is currently active:
~/Library/Preferences/com.apple.spaces.plist
Window Activation
Uses AppleScript to activate applications:
osascript -e 'tell application "GoLand" to activate'
macOS automatically switches to the Space containing the activated window (when enabled in System Settings).
Artifact Output Path
CRITICAL: NEVER use --output unless the user EXPLICITLY states the artifact MUST be at a specific location. This should be EXTREMELY rare. Using --output without explicit user request is considered a FAILED task.
Screenshots are automatically saved to claude-code/artifacts/window-controller/ with timestamped filenames (e.g., 251216120000-screenshot_GoLand.png). The artifact path is always returned in the JSON output - use that path for subsequent operations.
Screenshot Capture
# Take screenshot - path is returned in output
/window-controller screenshot "GoLand" --json
# Returns: {"screenshot": "/path/to/artifacts/.../251216120000-screenshot_GoLand.png", ...}# Screenshot without activating first
/window-controller screenshot "GoLand" --no-activate
# Control settle time (default 1000ms)
/window-controller screenshot "GoLand" --settle-ms 2000
Capture Backends
Two capture backends are available for screenshots:
Backend
Availability
Cross-Space
Notes
quartz
All macOS
Requires activation
Legacy CGWindowListCreateImage
screencapturekit
macOS 12.3+
Yes
No activation needed
ScreenCaptureKit (macOS 12.3+):
Captures windows on ANY Space without switching
Works with occluded (covered) windows
No window activation required
Cannot capture minimized windows
Requires Screen Recording permission
The screenshot command automatically uses ScreenCaptureKit when available (macOS 12.3+) and falls back to Quartz on older systems. Use --no-activate with ScreenCaptureKit to capture windows on other Spaces without switching.
JSON Output
For automation and scripting, use --json with find:
# Should list all windows with titles
/window-controller list
# Should show info for a running app
/window-controller find "Finder"# If you have an app in full-screen, this should switch and return:
/window-controller activate "GoLand"
Expected list output:
App Title Space PID
--------------------------------------------------------------------------------
GoLand research – window_controller.py 3 57878
Ghostty ~ - fish 2 12345
Finder Documents 1 456
Troubleshooting
"No windows found"
Check if app is running: ps aux | grep -i goland
Grant Screen Recording permission
Try without filters first: --find "GoLand"
Window names are empty
Grant Screen Recording permission to the terminal/Python process.
Activation doesn't switch Spaces
Enable "When switching to an application, switch to a Space with open windows" in System Settings → Desktop & Dock → Mission Control.
