A capture workflow for Claude Code: region select, preview, approve, auto-inject, and Claude-requested screenshots.
Select a region → preview → approve — screenshot lands in your conversation
Claude Code supports pasting clipboard images (Alt+V on Windows, Cmd+V in iTerm2). That covers quick one-off screenshots well. Snapview is the next level up:
- Claude-requested captures — Claude can ask for visual context via an auto-trigger hook, launching the capture UI without you switching windows. Native paste is always user-initiated.
- Preview before sharing — See exactly what you're about to inject into the conversation. Clipboard paste sends whatever is on the clipboard with no gate.
- Precision region selection — Dedicated overlay with drag-to-select, rather than relying on OS screenshot tools to get the right crop first.
- Automatic lifecycle — Temp files are created, tracked, and cleaned up after 24 hours. No leftover screenshots cluttering your desktop.
- Cross-platform consistency — Same workflow on Windows, macOS, and Linux/X11, regardless of terminal or clipboard support.
Requires Node.js 18+ and Claude Code.
npm i -g snapviewThe installer automatically registers the /snapview skill and auto-trigger hook into Claude Code.
snapviewA transparent overlay should appear on your screen. Press Esc to close it.
npm i -g snapview@latestThe postinstall script re-registers the skill and hooks automatically, so no extra steps are needed.
snapview uninstall # Remove skill, hooks, and settings
npm uninstall -g snapviewType /snapview in any Claude Code conversation — a transparent overlay appears, drag to select a region, approve the capture, and the screenshot is injected into context.
snapviewLaunches the capture overlay directly. On success (exit code 0), the temporary PNG file path is printed to stdout. Exit code 2 means the user cancelled; exit code 1 means an error occurred.
When enabled (default), Claude can automatically request a screen capture when it needs visual context. This works through a Claude Code Stop hook — when Claude includes a {"snapview_capture":true} signal in its response, the hook detects it and launches the capture UI. You still choose the region and approve before anything is shared.
The first time an auto-trigger occurs, a native OS dialog asks for your permission. This approval is persisted to ~/.snapview/config.json so you're only asked once.
Disable auto-trigger by setting SNAPVIEW_AUTO_TRIGGER to 0 in ~/.claude/settings.json:
{ "env": { "SNAPVIEW_AUTO_TRIGGER": "0" } }Snapview is an Electron app that creates a transparent overlay on every connected monitor simultaneously. You drag to select a region on any display — the other monitors dim automatically — preview the capture, then approve or retake. Each overlay uses its own display's native DPI, so captures are pixel-perfect even with mixed-resolution multi-monitor setups. The screenshot is saved as a temporary PNG in your system temp directory with automatic 24-hour cleanup.
Platform support:
- Windows — Works out of the box
- macOS — Requires Screen Recording permission (prompted on first use)
- Linux/X11 — Supported with GPU compositing workarounds applied automatically
| Environment Variable | Default | Description |
|---|---|---|
SNAPVIEW_AUTO_TRIGGER |
1 |
Enable (1) or disable (0) auto-trigger hook |
SNAPVIEW_RETENTION_HOURS |
24 |
Hours to retain temporary screenshots before cleanup |
Set these in ~/.claude/settings.json under the env key.
macOS requires Screen Recording permission for Snapview to capture your screen. If you get a black image or the capture fails:
- Open System Settings > Privacy & Security > Screen Recording
- Find your terminal app (Terminal, iTerm2, Warp, etc.) and enable it
- Restart your terminal — the permission change requires a fresh session
Note: macOS Sequoia may re-prompt for this permission periodically.
Snapview applies GPU compositing workarounds automatically for X11, but some setups still have issues:
- Wayland is not fully supported. If capture fails, try running with
XDG_SESSION_TYPE=x11or switch to an X11 session. - NVIDIA drivers on X11 — the
disable-gpuandenable-transparent-visualsflags are applied automatically. If the overlay is still opaque, check that your compositor supports transparent windows.
- Run
snapviewdirectly in your terminal to see error output - Ensure Node.js 18+ is installed:
node --version - On macOS, check that Screen Recording permission is granted (see above)
- Verify the hook is registered: check
~/.claude/settings.jsonfor aStophook entry pointing tosnapview-autotrigger.js - Ensure
SNAPVIEW_AUTO_TRIGGERis not set to0 - Reinstall to re-register hooks:
npm i -g snapview
Snapview stores screenshots as temporary PNGs in your system temp directory (os.tmpdir()/snapview/). These files may contain sensitive content visible on your screen at the time of capture:
- Files are automatically deleted after 24 hours (configurable via
SNAPVIEW_RETENTION_HOURS) - Set
SNAPVIEW_RETENTION_HOURS=1for faster cleanup in sensitive environments - Promoted screenshots (saved to
./screenshots/) are not auto-cleaned — manage these manually and consider addingscreenshots/to your.gitignore
The Electron renderer runs with full sandboxing, context isolation, and a strict Content Security Policy. No data leaves your machine — screenshots are stored locally and read directly by Claude Code.
bun install # Install dependencies
bun run dev # Electron dev mode with hot reload
bun run build # Production build
bun run typecheck # TypeScript checking
bun test # Run all testsSnapview has four layers:
- CLI entry (
bin/snapview.cjs) — Spawns the Electron process and captures stdout for the file path - Main process (
src/main/) — Window creation, IPC routing, screen capture viadesktopCapturer, PNG output - Preload bridge (
src/preload/) —contextBridgeexposing IPC channels with runtime validation - Renderer (
src/renderer/) — Canvas-based transparent overlay with drag-to-select and preview panel
Claude Code integration lives in claude-integration/SKILL.md (skill definition) and scripts/snapview-autotrigger.js (Stop hook).