Getting Started
Introduction
Fit images to a vision-LLM token budget before they are sent. For code, agents and pipelines, not for images pasted into a chat.
VisionSqueezer fits images to a token budget before they reach a vision model, using the current token rules of Claude 4.7+, OpenAI GPT-6/GPT-5.6, Gemini 3, and compatible legacy and open-weight models.
It cannot shrink an image you paste, drag, or
@-attach into a chat window. The client attaches it before any tool or hook runs, so it is billed at full size. VisionSqueezer saves tokens on images that pass through your code, your agent's tool calls, or files in your project. See where it saves tokens.Vision models do not "see" pixels the way you do. Each provider tokenizes images through its own internal grid math, and a handful of stray pixels can push an image into an extra tile row that doubles its cost. VisionSqueezer simulates that math and snaps your images to the cheapest valid boundary.
Why it matters
- Padding is expensive. Current Claude and OpenAI models count fixed-size patches; nearly empty edge patches still cost tokens.
- Tile spill-over is silent. A 769px-wide image costs the same as a 1536px one on a 768px-tile grid.
- Format ≠ tokens. Token cost is dimensional. AVIF/WebP/JPEG only affect file size and upload latency — not API token count.
Key Features
- Token budget —
--max-tokens Ndownscales until the target model's estimate fits. The MCP server defaults to 1600, which cut Claude tokens by ~66% on the sample photos while keeping composition, colour and large text. - Provider-aware resizing — Claude 28px patches, current OpenAI 32px patches, legacy OpenAI 512px tiles, and Gemini 768px tiles.
- Smart crop — saliency-based crop (Sobel-lite gradient energy) via
--smart-crop, plus default corner-tolerance padding strip. - AVIF / WebP / JPEG output — AVIF is typically 20–50% smaller than WebP, ~3× smaller than JPEG at equal quality.
- Auto-quality —
--auto-quality 0.95binary-searches quality to hit a perceptual SSIM target. - Batch / recursive mode — squeeze a whole directory tree, mirror structure with
--output-dir. - Machine-readable output —
--jsonand--dry-runfor pipelines. - Think in Code (Sandbox) — execute atomic image ops locally before sending to the LLM.
- Persistent analytics — cumulative token & USD savings in a local SQLite database.
- Universal MCP — one-liner integration for Claude Code, Cursor, Zed, VS Code, Windsurf, JetBrains.
- Python bindings —
pip install vision-squeezervia pyo3 wheels for Linux/macOS/Windows.