Screenshotting
Take screenshots to see what's on screen. Captures persist as files (unlike browsermcp snapshots which only exist in context).
Quick Reference
# Capture specific app window
${CLAUDE_SKILL_DIR}/scripts/look.py --app Ghostty
# Capture window by title match
${CLAUDE_SKILL_DIR}/scripts/look.py --app Chrome --title "LinkedIn"
# Capture full screen
${CLAUDE_SKILL_DIR}/scripts/look.py --screen
# List available windows
${CLAUDE_SKILL_DIR}/scripts/look.py --list
# List windows grouped by category
${CLAUDE_SKILL_DIR}/scripts/look.py --categories
# List only browser windows
${CLAUDE_SKILL_DIR}/scripts/look.py --category browsers
# Native resolution (skip resize)
${CLAUDE_SKILL_DIR}/scripts/look.py --app Safari --nativeCategories: browsers, terminals, editors, communication, documents, media, other
When to Use
Reactive (user asks):
- "Have a look at this"
- "Can you see what's on screen?"
- "What does it look like?"
- "Check the browser"
Proactive (verify state):
- After uncertain CLI operations (did it background?)
- When tool prompt state is unclear
- After browsermcp actions when snapshot isn't enough
- To verify visual changes actually happened
Documentation:
- Capture steps in a workflow
- Before/after comparisons
- Bug evidence with screenshots
When NOT to Use
- Browser-only tasks where browsermcp snapshot suffices
- When you just need to describe what's visible
- High-frequency captures that would clutter the directory
Anti-Patterns
| Pattern | Problem | Fix |
|---|---|---|
| Capture without purpose | Clutters context | Only screenshot when you need the visual |
| Skip --list first | Wrong window captured | List windows to find exact app/title |
| Native on large screens | Huge files, slow upload | Use default 1568px resize |
Resolution Strategy
Default: 1568px max dimension (~1,600 tokens, optimal for API)
| Option | Tokens | Use case |
|---|---|---|
| Default (1568px) | ~1,600 | Full detail, no resize penalty |
--max-size 735 | ~500 | Quick look, text readable |
--native | varies | When original resolution needed |
Why 1568px: Images larger than this get resized server-side anyway. Pre-resizing avoids upload latency while getting the same visual fidelity.
Output
Ephemeral (no path): Screenshots go to /tmp/claude-screenshots/ — auto-cleaned by OS, won't clutter project directories:
/tmp/claude-screenshots/2025-12-15-143022-chrome.pngPersistent (explicit path): For documentation workflows, specify where screenshots should live:
look.py --app Chrome ./docs/step3.pngDesign rationale: Quick looks are ephemeral by default. Documentation requires intentional placement. If a subagent is documenting, it should think about where artifacts belong.
How It Works
- Window enumeration: Uses macOS CGWindowList API (pure Quartz, no AppleScript)
- Capture: Uses
screencapture -l<windowid>for windows,screencapture -xfor screen - Resize: Uses
sips --resampleHeightWidthMaxfor efficient scaling
Key capability: Can capture windows even when covered or minimized.
Limitations
Scrollback: Only captures visible viewport. If content scrolled off screen, it won't be in the screenshot. Workaround: increase window size or pipe output to file.
Multiple monitors: Untested. --screen with -m flag captures main monitor only.
Window selection: Takes first match when multiple windows match filters. No "frontmost" heuristic yet.
Integration with browsermcp
browsermcp's browser_screenshot injects images directly into context but doesn't persist them as files. Use this skill when you need:
- Screenshots that persist beyond the conversation
- Captures of non-browser apps
- Captures of windows behind the browser
- Files to upload to Drive or include in docs
Permissions
Requires Screen Recording permission in System Preferences > Privacy & Security.
If capture fails with "check Screen Recording permissions", the user needs to grant permission to the terminal app (Ghostty, Terminal, iTerm, etc.).