Reducing Image Context Cost in Claude Code — Thinking in Pixel Dimensions and Cutting with Downscale, Crop, and Text Substitution

Passing screenshots or diagrams to Claude Code can burn through the conversation context faster than you would expect. What gets charged is image tokens, which scale with pixel dimensions, not the file size in KB or MiB. A heavily compressed JPEG and an uncompressed PNG cost the same number of tokens as long as the width and height are the same. This post walks through how Claude counts image tokens, confirms the long-edge resize behavior documented by Anthropic, and then separates the adjustments that help from the ones that do not.

The Codex and OpenAI API side of this optimization is written up in a companion post: Reducing Image Context Cost in Codex — Cutting Tokens with 32×32 Patches and detail: low / high / original on GPT-6.1, GPT-6, and GPT-5.6 Models.

Image tokens depend on pixel dimensions

Anthropic’s vision documentation explains that Claude processes images in 28×28 px patches, and each patch is one visual token. The token count of an image is therefore:

⌈width (px) ÷ 28⌉ × ⌈height (px) ÷ 28⌉ = visual tokens

File size, compression ratio, and color depth are not part of this formula. Lowering JPEG quality, converting to grayscale, or stripping EXIF does not change the token count as long as the pixel dimensions stay the same.

Applying the formula, a 1920×1080 image comes to 69 × 39 = 2,691 tokens, and a 960×540 image comes to 35 × 20 = 700 tokens. The area is one quarter, so the token count drops to about one quarter as well.

There is one more behavior that matters here. The documentation states that each model has a long-edge limit and a visual-token limit, and an image that exceeds either one is downscaled before processing. The limits come in two tiers.

The Claude 4.7 and later models you use in Claude Code, such as Sonnet 5.5 and Opus 5.5, fall in the high-resolution tier. In the documentation’s table, a 1920×1080 image is not resized in the high-resolution tier and costs 2,691 tokens, while in the standard tier it is downscaled to 1456×819 and costs 1,560 tokens. Pasting a raw 3840×2160 4K screenshot does not preserve more detail: the high-resolution tier downscales it to 2576×1449 (4,784 tokens) and the standard tier to 1456×819 (1,560 tokens), and the resize is an interpolation step that makes small text harder to read. You pay for the resized dimensions, but you do not get finer detail by starting larger. The limits differ by model, so check the documentation for the model you use.

The table below summarizes which adjustments have an effect.

One note on ASCII art: an 80×40 character grid still costs several thousand text tokens, and the detail is coarser than the original image. Beyond showing a very simple frame or layout, writing the same content in prose or giving a Mermaid diagram usually carries more information for fewer tokens.

Work through the options in order of impact

Avoid sending the image when you can

For development work with Claude Code, a lot of the information you want to convey does not depend on the image. Sending it as text or structured data uses fewer tokens and is also easier for Claude to work with programmatically.

• For UI implementation or edits, send the HTML, CSS, or an excerpt of the DOM structure
• For flowcharts and screen transition diagrams, send the Mermaid source
• For tables, send CSV or a Markdown table
• For charts, send the underlying numeric data (CSV or JSON)
• For an error dialog, paste the error message as text instead of the screenshot
• For logos and icons, send the SVG source

For example, an error shown in the terminal is usually fully captured by this text:

Error: Cannot find module 'react'
File: src/main.tsx
Line: 12

If you only need the characters inside an image, extract them with OCR or fetch the original log. On the other hand, shapes, the placement of UI elements, and the relationships in a diagram are lost in text, so send the image alongside the text when those matter. Color, spacing, and overall visual polish also cannot be judged from structured data alone.

Crop to the region that matters

Cut out the part of the screen where the problem appears rather than sending the full screen. A section of the header, a single button, or only the error dialog reduces the processed area considerably. Cropping a 480×270 region out of a 1920×1080 screenshot cuts the area to 1/16, and the image tokens drop to 18 × 10 = 180, roughly 1/15 of the original.

Because pixel dimensions are what you pay for, sending the region you actually need at full resolution gives you more usable information per token than shrinking the whole screen. Try cropping before downscaling.

Switch resolutions in stages

Separate the step where you check the overall structure from the step where you inspect details, and use a different resolution for each.

1. To see the overall layout, send a version scaled down to about 960 px on the long edge (around 700 tokens)
2. When you need small text or fine details, crop the relevant region from the original and send it as a follow-up

The image quality guidance in the vision documentation makes the same point: an oversized image gets resized and small text can become hard to read, so pre-resize it, crop it, or both before sending. The rule of thumb is: show the whole thing small, then show the part that matters at full resolution.

Automate preprocessing with a command

ImageMagick can process images automatically before you send them. ImageMagick 7 uses the magick command, and ImageMagick 6 uses convert.

# Trim surrounding margins
magick input.png -trim +repage output.png
 
# Shrink to fit within 960x540 (images already smaller are not enlarged)
magick input.png -resize '960x540>' output.png
 
# Strip metadata to reduce file size (does not change token count)
magick input.png -strip output.png

To combine several steps, you can write:

magick screenshot.png \
  -trim +repage \
  -resize '960x540>' \
  -strip \
  context.png

The -trim option decides what counts as margin from the color at the edges of the image. If the background is not a single color, it can remove parts you need, so check the result before you use it.

A useful setup is to watch your screenshot folder with something like fswatch and run this pipeline on every new file. It takes the “I forgot to resize again” step out of the loop.

Do not keep the image in the running history

In Claude Code, an image you have sent stays in the conversation history and is included in every subsequent turn. If you paste a 2,691-token image on turn 1 of a 10-turn session, that image is included in the context on every one of those turns. When /compact or auto-compaction replaces the history with a text summary, the image itself does not survive. And once a request reaches the limit on image count or total image size, Claude Code removes a batch of the oldest images from what it sends, and Claude can no longer see them. Leaving an image in the thread does not guarantee you can still reference it later.

So once you have extracted what you need from the image, write the findings into a text note (CLAUDE.md, .claude/context/*.md, and so on) and avoid resending the same image. A summary loses fine detail, of course. If a detail becomes relevant later, crop that region and send it again on its own.

For workflows that take screenshots repeatedly (before/after comparisons during UI work, for example), sending the diff region instead of a full screenshot each turn keeps the per-turn image cost flat. In Playwright-driven agent environments, building the diff into the preprocessing pipeline keeps this habit automatic.

Where to start by input type

In practice, three habits remove most of the waste: downscale or crop; replace what can be expressed as text or structured data; and do not resend the same image.

The opposite failure mode matters too: cutting images too aggressively leads to follow-up questions and resends that end up costing more context than sending a slightly larger image once. The reliable way to tune this is to run the same image and same question at a few sizes and compare the token count against the accuracy of the answer. What you actually want to minimize is the total tokens spent to complete one task, not the tokens spent on a single image.

That’s all from working out that image tokens follow pixel dimensions rather than file size, and how to cut what you send through downscaling, cropping, text substitution, and keeping images out of history, from the Gemba.

References

• Anthropic Vision documentation
• ImageMagick
• Mermaid
• Reducing Image Context Cost in Codex — Cutting Tokens with 32×32 Patches and detail: low / high / original on GPT-6.1, GPT-6, and GPT-5.6 Models