SnapCoder

Command-line interface for taking website and native window screenshots — AI agent friendly

Installation

# Global installation (recommended)
npm install -g snapcoder

# Or locally in your project
npm install snapcoder

Usage

Taking a single screenshot

Screenshots are saved by default in the ./snapcoder/ subdirectory of your current working directory.

# Full page screenshot (saved in ./snapcoder/)
snapcoder capture https://example.com

# Visible area screenshot
snapcoder capture https://example.com --mode visible

# Custom output path
snapcoder capture https://example.com --output my-screenshot.png

# Custom browser size
snapcoder capture https://example.com --width 1280 --height 720

# Selection area screenshot
snapcoder capture https://example.com --mode selection --selection "100,100,800,600"

Capturing a native window (macOS)

Capture any on-screen window — Tauri, Electron, native macOS apps, anything with a window.

# List all visible windows
snapcoder window --list

# Capture the first window matching "Safari" (substring match on app name or title)
snapcoder window Safari

# Match on window title text
snapcoder window "Inbox"

# Custom output path
snapcoder window MyTauriApp --output app.png

Requirements:

• macOS only (Linux/Windows on the roadmap — exit code 2 is returned on unsupported platforms)
• Xcode Command Line Tools (provides swift for window enumeration): xcode-select --install
• Screen Recording permission for the terminal/app running snapcoder. Without it macOS will only expose snapcoder's own windows. Grant via System Settings → Privacy & Security → Screen Recording.

Coming later: snapcoder electron <port> for Electron apps started with --remote-debugging-port=<port> (full DOM access via CDP, not just a pixel grab).

Batch screenshots

# Create urls.txt with one URL per line
echo "https://example.com" > urls.txt
echo "https://google.com" >> urls.txt

# Run batch capture (defaults to ./snapcoder/)
snapcoder batch urls.txt

# Or with custom directory
snapcoder batch urls.txt --output-dir ./my-screenshots

file:// URLs are rejected in batch mode: a URL list is often generated or supplied by something other than you, and a local path there turns a screenshot run into a file read. Use snapcoder capture file:///path/to/page.html for local files.

Options

• --mode <mode>: Screenshot mode (visible, fullpage, selection) - default: fullpage
• --output <path>: Output file path - default: auto-generated
• --width <width>: Browser width - default: 1920
• --height <height>: Browser height - default: 1080
• --wait <ms>: Wait time after page load - default: 2000
• --headless <mode>: Headless mode (true, false, new) - default: true
• --selection <coords>: Selection coordinates for selection mode (x,y,width,height)
• --proxy <url>: Proxy server URL (e.g., http://proxy.company.com:8080)
• --ignore-ssl: Ignore SSL certificate errors (useful for corporate networks)
• --no-sandbox: Disable the Chromium sandbox - only for containers or CI images that block it. Leaving the sandbox on is what keeps a malicious page from reaching the machine.

Version & Help

# Show version
snapcoder -v
snapcoder --version

# Show changelog
snapcoder changelog

# Show help
snapcoder --help
snapcoder capture --help

For AI Agents

This tool is specifically designed for use by AI agents:

# Simple usage
snapcoder capture https://example.com

# JSON output for parsing (future feature)
snapcoder capture https://example.com --format json

# Batch processing
snapcoder batch urls.txt --output-dir ./output

Features

• ✅ Full page screenshots with optimized height detection (no white borders)
• ✅ Visible area screenshots
• ✅ Selection area screenshots
• ✅ Native window capture by title (macOS — Tauri, Electron, any app)
• ✅ Batch processing
• ✅ Auto-generated filenames with timestamp
• ✅ Customizable browser viewport
• ✅ Headless and non-headless modes
• ✅ Automatic image compression for Claude Code compatibility (< 5 MB)
• ✅ Corporate network support (proxy + SSL certificate handling)
• ✅ File:// URL support for local HTML files
• ✅ AI agent friendly CLI interface

Technical Details

The CLI tool uses:

• Puppeteer for browser automation
• Commander.js for CLI interface
• Chalk for colored output
• Sharp for image compression and optimization
• Swift + CGWindowListCopyWindowInfo for window enumeration (macOS)
• screencapture -l <id> for the actual native window capture (macOS)

Code layout:

index.js              ← Commander routing only
lib/
  web.js              ← Puppeteer pipeline (capture, batch, full-page)
  output.js           ← Filename + compression helpers (shared)
  platform.js         ← OS dispatch + UnsupportedPlatformError
  window/
    macos.js          ← Native window capture for macOS
    list-windows.swift ← CGWindowList enumerator

File Naming

Screenshots are automatically named as: snapcoder_{domain}_{YYYY-MM-DD_HH-MM-SS}.png

For example: snapcoder_example_2024-06-15_14-30-25.png