# VisionSqueezer
> LLM-native image optimization middleware & MCP server. Reduces vision model token consumption by mathematically snapping images to provider-specific tile boundaries.
## Key Features
- **Provider-Aware Resizing:** Simulate exact internal grid math for Claude (area-based), GPT-4o / GPT-5 (512px tiles), and Gemini (768px tiles).
- **Smart Crop:** Saliency-based crop (Sobel-lite gradient energy) keeps the high-information region and discards uniform borders — opt-in via `--smart-crop`.
- **Padding Stripping:** Aggressive corner-tolerance background crop (default) for screenshots with solid borders.
- **AVIF / WebP / JPEG Output:** AVIF (default `--format avif`) is typically 20–50% smaller than WebP, ~3× smaller than JPEG, at equal quality.
- **Auto-Quality:** `--auto-quality 0.95` binary-searches quality in [40,95] to hit a target SSIM, picking the smallest file that still passes a perceptual threshold.
- **Batch / Recursive Mode:** Pass a directory; `--recursive` walks subdirs, `--output-dir` mirrors structure.
- **Machine-Readable Output:** `--json` emits a structured record (per-file or aggregate in batch). `--dry-run` runs the full pipeline without disk writes.
- **Think in Code (Sandbox):** Execute atomic operations (crop, grayscale, binarize, resize, contrast, brightness) locally before sending to LLM.
- **Persistent Analytics:** Track token and USD savings in a local SQLite database (`~/.vision-squeezer/stats.db`).
- **Universal MCP:** One-liner integration for Claude Code, Cursor, Zed, VS Code, Windsurf, JetBrains via `npx -y vision-squeezer`.
- **Python Bindings:** `pip install vision-squeezer` exposes `optimize_image`, `estimate_tokens`, and `optimal_dimensions` via pyo3 wheels for Linux/macOS/Windows.
## Core Commands
- `vision-squeezer <image> [options]`: Optimize a single image.
- `vision-squeezer <directory> --recursive [--output-dir DIR]`: Batch optimize a tree.
- `vision-squeezer stats`: View cumulative savings analytics.
- `vision-squeezer setup-hook`: Print shell integration (eval) script for Zsh/Bash.
## Detailed Documentation
- [Full LLM Documentation](llms-full.txt)
- [Project README](README.md)
- [Mission Statement](MISSION.md)