appsnap 0.2.0
Fast Windows screenshot tool for AI coding agents
License: MIT
Requires Python: >=3.10
Keywords: ai-agent, automation, cli, desktop, screenshot, windows

# 📸 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

```bash
# 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**

```bash
# 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)**

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

**Common Commands:**

```bash
# 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

```python
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

```powershell
$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:

```bash
# 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

```bash
# 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](LICENSE) for details

## 🙏 Acknowledgments

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

- [Pillow](https://github.com/python-pillow/Pillow) - Screenshot capture and image processing
- [fuzzywuzzy](https://github.com/seatgeek/fuzzywuzzy) - Fuzzy string matching
- [pywin32](https://github.com/mhammond/pywin32) - Windows API access

## 🤝 Contributing

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

For maintainers publishing to PyPI, see [PUBLISHING.md](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 🤖❤️