vision-squeezer 0.8.1

Fit images to a vision-LLM token budget before you send them. Library, CLI and MCP server for code, agents and pipelines.
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
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

---
title: Batch Mode and JSON Output
description: Squeeze whole directory trees and emit structured output for pipelines.
navigation:
  icon: i-lucide-package
---

## Batch mode

Point Squeezer at a directory instead of a single file:

```bash [Terminal]
vision-squeezer ./assets --recursive --output-dir ./assets-optimized --model gemini
```

- `--recursive` walks every subdirectory.
- `--output-dir` mirrors the source tree into the destination, preserving folder structure.

## JSON output

`--json` emits a structured record instead of the human-readable savings table. In single-file mode it's one record; in batch mode it's an aggregate.

```bash [Terminal]
vision-squeezer image.png --model claude --json
```

```json
{
  "model": "claude",
  "original_tokens": 5344,
  "optimized_tokens": 4194,
  "tokens_saved": 1150,
  "bytes_before": 512000,
  "bytes_after": 365000,
  "size_reduction_pct": 28.6,
  "quality": 75
}
```

## Dry run

Combine `--json --dry-run` to estimate impact across a tree without writing files or updating the stats database:

```bash [Terminal]
vision-squeezer ./screenshots --recursive --json --dry-run --model gpt6
```

This is the recommended way to gate a CI pipeline on projected token savings.

## Persistent analytics

Every real (non-dry-run) optimization is recorded in a local SQLite database at `~/.vision-squeezer/stats.db`.

```bash [Terminal]
vision-squeezer stats
```

| Field | Description |
| --- | --- |
| `timestamp` | When the optimization ran |
| `model` | Target model |
| `original_tokens` / `optimized_tokens` | Token counts before/after |
| `bytes_before` / `bytes_after` | File size before/after |
| `mode` | `standard`, `ocr`, or `auto` |

In Claude Code, the `/vision-stats` skill reads this database directly with zero MCP overhead.