claude-code - 💡(How to fix) Fix [BUG] Read tool downsamples PNG based on file size, not pixel area — same image at smaller bytes arrives readable

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet (closest match #56236 is macOS-only and doesn't isolate the byte-size axis)
• This is a single bug report
• I am using the latest version of Claude Code

What's Wrong?

The Read tool's image delivery path applies an aggressive downscale before the model sees the image, and the cliff is driven by bytes on disk, not pixel area. A 4K screenshot saved as a normal PNG arrives mushy and illegible. The same image run through pngquant (visually-lossless palette quantization, ~70% smaller bytes, identical visual content) arrives at full fidelity. Same dimensions, same look, fewer bytes → readable.

The paste pipeline (Alt+V) does not exhibit this. Same PNG file pasted directly arrives at full fidelity at the same byte sizes that crush via Read. Changelog 2.1.119 claims the two pipelines share a token budget:

"Improved image handling: pasted and attached images are now compressed to the same token budget as images read via the Read tool."

In practice they don't behave the same. The fix that landed for paste doesn't apply (or no longer applies) to Read.

What Should Happen?

The Read pipeline should match the paste pipeline. Paste arrives correctly at the same byte counts that fail via Read — the precedent exists in-product.

Any size cap should be based on decoded pixel area, not encoded file bytes. PNG file size depends heavily on the encoder (palette vs truecolor, zlib level, filter choice); the model only ever sees decoded pixels, so byte count is the wrong signal.

Error Messages/Logs

No error — the model silently receives a degraded image and proceeds.

Steps to Reproduce

Requires pngquant (TinyPNG-equivalent CLI; scoop install pngquant on Windows). Any PNG that's a few hundred KB on disk will do — a screenshot of a UI on a 4K monitor is convenient.

1. Take a 4K screenshot. The PNG should land on disk at ~200–500 KB. In any image viewer it should look crystal clear.
2. In Claude Code, Read that file and ask Claude: "Describe what you see and tell me whether the image looks pixelated, blurry, or low-resolution to you." Claude will spontaneously report the image arrived as a small / blurry / thumbnail-quality version, even though the file on disk is high-resolution. (This is the diagnostic — Claude is reporting on what it actually received, no leading required.)
3. Compress the file with pngquant:

   pngquant --output compressed.png --force source.png

   This cuts bytes by 60–80% on UI/screenshot art with no visible change — open both side-by-side in any viewer to confirm.
4. Read compressed.png and ask the same self-report question. Claude now reports the image arrived sharp at full resolution.

The two files have identical visible content (pngquant changes palette encoding, not pixels you can see); the only thing that moved is bytes on disk. That alone flips Claude's view from blurry-thumbnail to full-resolution.

Bonus cross-check showing the paste pipeline doesn't have this bug:

1. Paste the original uncompressed file with Alt+V and ask the self-report question. Claude reports the image arrived sharp — paste delivers the same byte count as the Read that came through mushy, but without downsampling.

Claude Model

Opus 4.7

Is this a regression?

Possibly — changelog 2.1.119 (Apr 23, 2026) explicitly aligned paste and Read token budgets. If they were ever symmetric, this is a regression from that fix.

Last Working Version

Unknown — observed on 2.1.139.

Claude Code Version

2.1.139

Platform

Anthropic API

Operating System

Windows 11

Terminal/Shell

PowerShell 7 (pwsh) in VS Code integrated terminal

Additional Information

Related:

• #56236 — same root cause filed from macOS, no isolation of the byte-size axis
• #35866 (closed) — broader meta-issue, explicitly notes paste works and Read doesn't