Optical context compression · Claude Code

68,213 characters → one 3,588-token image.

opticompress

A local proxy that renders bulky Claude Code context into dense images, so the model reads pixels instead of text tokens. It only makes the swap when the pixels actually cost less than the text — which turns out to be rarer than you'd hope.

shell 
git clone https://github.com/stampixel/opticompress  # not on PyPI
pip install -e opticompress          # or: uv pip install -e .
optc proxy                            # prints the line below
ANTHROPIC_BASE_URL=http://127.0.0.1:47821 claude
7.6× peak compression (measured)
19.0 source chars / image token
~68k chars in one 5×8 image
0 lines of config

The idea

DeepSeek-OCR showed you can reconstruct a page of text from a compact grid of vision tokens — optical context compression (arXiv:2510.18234). opticompress brings that to Claude Code: take the bulky context, render it to a dense PNG, and let the model read pixels instead of text tokens. A hook can't swap text for an image, so opticompress runs as a small local proxy you point ANTHROPIC_BASE_URL at.

The catch is how Claude prices pixels. An image costs ceil(w/28) × ceil(h/28) visual tokens — capped at 1568 on the standard tier, or 4784 at a 2576 px edge on high-res readers (Fable 5 · Opus 4.8 · Sonnet 5). Render text at a size you can read and you'll usually pay more tokens than the text itself. The savings only show up when the content is bulky and the render is dense, and dense trades fidelity for compression: the paper reports ~97% reconstruction under 10×, sliding to ~60% near 20×.

So opticompress only images bulky blocks, prices each one before committing, and never hands an exact string to the pixels. It's lossy on zero-redundancy content, which is exactly why identifiers ride along as a text factsheet and the default allowlist is a Fable-class reader.

How it works

Three hops. Your requests flow through a proxy that rewrites only what pays off, and forwards everything else byte-for-byte.

Client

Claude Code

Point ANTHROPIC_BASE_URL at the local proxy. Nothing else changes — no plugins, no hooks, no config.

Proxy

opticompress
render + gate

Rewrites POST /v1/messages: bulky tool_result bodies and pasted context become dense PNGs — but only past the profitability gate. The live prompt, model output, and short blocks pass through.

Upstream

Anthropic

The API sees a smaller request and streams the response back verbatim. On any error, the original bytes are forwarded untouched.

Profitability-gated

Every candidate block is rendered once and priced. It only becomes an image when image tokens plus factsheet overhead beat the text baseline — with a 1.10× safety bias that tips ties toward passing through.

Lossless identifiers

A deterministic factsheet extracts SHAs, paths, UUIDs, flags and versions and ships them as text beside the image, so precision-critical strings survive a render that is otherwise lossy.

Fail-safe proxy

It never fails a request it can't transform. On any error — parse, render, or upstream — it forwards the original request unchanged. Worst case, it's a plain passthrough.

Measured, not claimed

JSONL telemetry prices the imaged request and the text counterfactual under the same observed cache state. Savings can be negative, and are never floored or hidden.

Results

A density sweep on the tool's own source — ~68k chars of dense Python — on the high-res tier (Fable 5), with both sides measured through count_tokens (text baseline: 27,274 tokens). Denser cells pack more chars per image token, but past a point the image costs more than the text would.

Cell Pages Image tokens Chars / img token Text tokens Ratio
5×8 1 3,588 19.0 27,274 7.6×
8×16 3 11,408 6.0 27,274 2.4×
12×24 6 25,484 2.7 27,274 1.1× barely beats text; bigger cells lose

Both sides are measured through Anthropic's count_tokens (reproduce with optc bench --count-tokens). This is dense code, the favorable case — sparse prose compresses far less and often loses.

A dense 5×8 grayscale render of opticompress's own Python source, packed edge to edge as a single image.
A 5×8 render of opticompress's own source — ~68k chars the model reads as one ~3,588-token image.
shell 
optc bench                       # density sweep + fidelity table (est.)
optc bench --count-tokens        # measure the real baseline via the API
optc render file.py --out ./out  # page-NNN.png + factsheet.txt + report

When it saves vs. when it costs more

  • Saves on bulky, low-signal data — long file reads, command dumps, pasted logs — rendered dense enough to clear the gate.
  • Costs more on short or already-compact text. At legible cell sizes the image tokens exceed the text, so opticompress leaves it as text (see the 12×24 and 16×32 rows above).
  • Always text for exact identifiers. Rendering is lossy on zero-redundancy strings, so SHAs, UUIDs, paths and flags stay in the factsheet — never entrusted to pixels.

Cite

The idea here is entirely DeepSeek-OCR's — opticompress just applies it to Claude's tokenizer. If you build on it, cite the paper.

citation · bibtex 
@misc{wei2025deepseekocr,
  title={DeepSeek-OCR: Contexts Optical Compression},
  author={Wei, Haoran and Sun, Yaofeng and Li, Yukun},
  year={2025},
  eprint={2510.18234},
  archivePrefix={arXiv},
  primaryClass={cs.CV},
  doi={10.48550/arXiv.2510.18234},
  url={https://arxiv.org/abs/2510.18234}
}

Read the paper → opticompress on GitHub →