vision-squeezer 0.6.2

LLM-native image optimization middleware & MCP server. Reduces vision model token consumption by snapping to tile boundaries.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

---
title: Options
description: Full reference for every VisionSqueezer CLI flag.
navigation:
  icon: i-lucide-sliders-horizontal
---

## Reference

| Flag | Description |
| --- | --- |
| `--model <name>` | Target model alias; core profiles plus popular families such as `kimi`, `glm`, `pixtral`, `gemma`, `internvl`, `llava`, and `minimax`. |
| `--format jpeg\|webp\|avif` | Output encoding. AVIF is the default for new pipelines. |
| `--quality 1-100` | Output quality (default `75`). |
| `--auto-quality 0.0..1.0` | Binary-search quality in `[40,95]` to hit an SSIM target. |
| `--smart-crop` | Edge-energy (Sobel-lite) crop. Best for photographic content. |
| `--ops '<JSON>'` | Execute [Sandbox](/guides/sandbox) operations. |
| `--output <path>` | Custom output destination (single-file mode). |
| `--output-dir <path>` | Output root (batch mode, mirrors structure). |
| `--recursive` | Walk subdirectories in batch mode. |
| `--max-tiles <N>` | Hard cap on the token budget. |
| `--json` | Machine-readable JSON output (single-file or batch aggregate). |
| `--dry-run` | Run the full pipeline without writing to disk or updating the stats DB. |

## Quality vs. auto-quality

`--quality` is a fixed encoder setting. `--auto-quality` is smarter: it binary-searches the quality range and lands on the **smallest file that still passes** a perceptual SSIM threshold.

```bash [Terminal]
# Fixed quality
vision-squeezer image.png --quality 80

# Target perceptual fidelity, minimize bytes
vision-squeezer image.png --auto-quality 0.95
```

Use `--auto-quality 0.95` when bandwidth matters and you can tolerate slight perceptual loss.

## Crop strategy

- **Default (corner-tolerance):** strips solid-color padding. Best for screenshots with uniform borders.
- **`--smart-crop`:** keeps the high-information region using gradient energy. Best for photos and saliency-heavy content.

## Estimate before writing

```bash [Terminal]
vision-squeezer image.png --model gpt6 --json --dry-run
```

`--json --dry-run` reports token impact with zero side effects — ideal for pipelines that gate on savings before committing.