appsnap 0.2.0

Fast Windows screenshot tool for AI coding agents

📸 appsnap

Fast Windows screenshot tool for AI coding agents

appsnap is a simple, fast CLI tool for capturing screenshots of Windows application windows. Perfect for AI agents that need to verify UI changes during development iterations.

✨ Features

• 🎯 Window-specific capture - Target apps by name with fuzzy matching
• � Bulk capture - Screenshot all windows at once for testing
• 🚀 Fast - Screenshots in ~0.1-0.3 seconds
• 🤖 Agent-friendly - JSON output and stdout paths for easy parsing
• 📁 Smart defaults - Temp directory with auto-cleanup
• 🔍 List windows - See all capturable windows
• 🎨 DPI-aware - Handles high-DPI displays correctly
• 🔢 Duplicate handling - Auto-numbers windows with identical titles

🚀 Quick Start

Installation

# Install from PyPI with uvx (recommended)
uvx appsnap

# Or install as a tool with uv
uv tool install appsnap

# Or with pipx
pipx install appsnap

# Install from GitHub (development version)
uv tool install git+https://github.com/detroittommy879/appsnap.git

# Development mode (local testing)
git clone https://github.com/detroittommy879/appsnap.git
cd appsnap
uv venv
uv pip install -e .

Usage

Option 1: After activating venv

# Activate the virtual environment first
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # Linux/Mac

# Then use appsnap directly
appsnap --list
appsnap "Visual Studio Code"

Option 2: Using uv run (no activation needed)

# Run from within the appsnap directory
cd appsnap
uv run appsnap --list
uv run appsnap "Chrome" --output screenshot.png

Common Commands:

# List all capturable windows
appsnap --list

# Capture a window (saves to temp directory)
appsnap "Visual Studio Code"

# Capture with custom output path
appsnap "Chrome" --output screenshot.png

# JSON output for agents
appsnap "Notepad" --json
# {"path": "C:\\Temp\\appsnap\\appsnap_20260202_153045.png", "window": "Notepad", "bbox": [100, 200, 800, 600]}

# Adjust fuzzy matching threshold (0-100, default 70)
appsnap "VS" --threshold 60

# Capture ALL windows to a folder (great for testing!)
appsnap --all ./screenshots

# Capture all with JSON summary
appsnap --all ./test-screens --json

🤖 AI Agent Integration

Claude Desktop Skill

Add to your agent prompt or skill:

When you need to verify UI changes, use: appsnap "App Name" --json
Parse the JSON output to get the screenshot path and window metadata.

Python Integration

import subprocess
import json

result = subprocess.run(
    ["appsnap", "Chrome", "--json"],
    capture_output=True,
    text=True
)
data = json.loads(result.stdout)
screenshot_path = data["path"]

PowerShell Integration

$result = appsnap "VSCode" --json | ConvertFrom-Json
Write-Host "Screenshot: $($result.path)"

📖 CLI Options

positional arguments:
  window_name           Window title to search for (fuzzy matching)

options:
  -h, --help            Show this help message and exit
  -l, --list            List all capturable windows
  -a DIR, --all DIR     Capture all windows to specified directory
  -o PATH, --output PATH
                        Output file path (default: temp directory)
  -t N, --threshold N   Fuzzy match threshold 0-100 (default: 70)
  -j, --json            Output JSON with path and metadata

Bulk Capture Example

The --all flag is perfect for quickly testing that all windows capture correctly:

# Capture all windows to a test folder
uv run appsnap --all ./test-captures

# Output:
# Capturing 42 window(s) to C:\path\to\test-captures...
#
# [OK] Visual Studio Code
# [OK] Chrome - Google Search
# [OK] Task Manager
# [OK] Settings
# [OK] PowerShell_1  # Auto-numbered duplicate
# [OK] PowerShell_2  # Auto-numbered duplicate
# ...
#
# Complete: 40 successful, 2 failed
# Screenshots saved to: C:\path\to\test-captures

Windows with the same title automatically get numbered (e.g., PowerShell_1.png, PowerShell_2.png).

🛠️ How It Works

1. DPI Awareness - Sets process DPI awareness for correct scaling on high-DPI displays
2. Window Enumeration - Uses Win32 API to enumerate all visible, non-minimized windows
3. Fuzzy Matching - Finds windows using fuzzywuzzy for flexible name matching
4. Direct Window Capture - Uses Win32 PrintWindow API to capture window content directly (works even when partially occluded)
5. Output - Saves to temp or custom location, prints path to stdout for easy agent parsing

🔧 Development

# Clone and install dev dependencies
git clone <repo>
cd appsnap
uv pip install -e ".[dev]"

# Run tests
uv run pytest

# Run with local changes
uv run appsnap --list

🐛 Troubleshooting

"No window found matching..."

• Use appsnap --list to see exact window titles
• Try lowering the threshold: --threshold 60
• Make sure the window is visible (not minimized)

Screenshots are blank, wrong window, or multiple windows

v0.1.1 Fix: Switched to Win32 PrintWindow API for direct window content capture.

This method captures the actual window content, not screen regions, so it:

• Works correctly on multi-monitor setups
• Captures partially occluded windows
• Handles DPI scaling properly

If you still have issues:

• Ensure the window is not minimized (minimized windows cannot be captured)
• Some apps (especially GPU-accelerated ones) may not respond to PrintWindow correctly
• Try bringing the window to foreground if capture fails

DPI/Scaling issues

The tool automatically handles DPI awareness. If you see incorrect sizing:

• Ensure Windows display scaling is consistent
• Check that the app respects DPI settings

📝 License

MIT License - see LICENSE for details

🙏 Acknowledgments

Built on the excellent Windows-MCP project patterns and libraries:

• Pillow - Screenshot capture and image processing
• fuzzywuzzy - Fuzzy string matching
• pywin32 - Windows API access

🤝 Contributing

Contributions welcome! Please feel free to submit issues or pull requests.

For maintainers publishing to PyPI, see PUBLISHING.md for detailed instructions on:

• Setting up GitHub Actions for automated PyPI releases
• Manual publishing workflow
• AI agent skill integration
• Troubleshooting

---

Made for AI agents, by developers 🤖❤️