Key Takeaways

  • A capture ID survives a compact because it is an address, not a message. Everything Claude Code brings back after compaction comes back off your disk, and a pasted PNG has nowhere to be read back from.
  • Anthropic documents the eviction plainly. On image limits, the prompt-caching docs say "Claude can no longer see the removed images. If Claude needs one of them again, share it again."
  • Image limits fire independently of compaction. Claude Code removes a batch of the oldest images and PDFs from a request when it would exceed the API's per-request image cap, which can happen while your context meter still looks healthy.
  • Re-pasting is expensive. Under Anthropic's documented formula a 1512 by 982 window capture is 1,944 visual tokens. Four re-pastes of one window is 7,776 tokens of evidence the model may already have described in prose.
  • The API has a second eraser. Context editing's clear_tool_uses_20250919 strategy clears the oldest tool results in chronological order and leaves placeholder text in their place.
  • Stash composites the ID onto the pixels because Anthropic's vision docs state Claude does not parse or receive image metadata. Eight characters in a banner is the part of a screenshot a model can reliably carry forward.
  • One line in CLAUDE.md outlives the compact, since project-root CLAUDE.md is re-injected from disk. That is where the instruction to re-query a capture ID belongs.

Give the Agent a Pointer, Not a Picture

Put an eight-character capture ID in the prompt and let the agent fetch the capture itself. The ID keeps working after a compact, after a --resume the next morning, and across every subagent in the session, because it names a bundle on your Mac instead of occupying a slot in the conversation.

Look at what Claude Code restores after compaction and the pattern is obvious. Your project-root CLAUDE.md comes back because it is a file. Up to five recently touched files come back because they are files. Invoked skills come back because they are files. Every single thing on that list has an address on disk that can be read a second time.

A screenshot you pasted has no address. It is a block of base64 inside a message, and a summary of that message is text about an image, not the image.

What a Compact Actually Reloads

Claude Code's context-window documentation has a section titled "What survives compaction." It is worth reading once in full, because it changes how you structure a long session. The short version:

In the session After the compact
System prompt and output style Kept
Project-root CLAUDE.md and unscoped rules Re-injected from disk
Auto memory Re-injected
The plan from plan mode Kept
Path-scoped rules and nested CLAUDE.md Summarized away
Files Claude read or edited Re-reads up to five, most recently modified first. "A file over 5,000 tokens comes back as a path reference without its content"
Invoked skill bodies Re-injected, capped at 5,000 tokens per skill and 25,000 total
Background commands and subagents Keep running
Pasted screenshots Not on the list

That last row is the one that costs you an afternoon. The summary keeps your sentence about the misaligned toolbar and drops the picture of it, so the model keeps reasoning about a bug it can no longer see. You get a confident answer built on its own earlier prose. Hour one was fine. Hour three is fiction.

Images Go Before the Compact Does

Compaction is the famous one, and it is not the first eraser you hit. Claude Code's prompt-caching documentation has a section called "Accumulating many images," and it describes a request-level limit rather than a context-level one:

"The API limits how many images and PDFs each request can carry." When a request would go past it, "Claude Code removes a batch of the oldest images and PDFs from what it sends." Then: "Claude can no longer see the removed images. If Claude needs one of them again, share it again."

Read the last sentence as the spec it is. Sharing it again is the documented recovery path, and sharing it again costs the full image price a second time. Do that four times in a debugging session and the screenshot is one of the more expensive things in your context window.

On the API side there is a third mechanism. Anthropic's context editing, behind the context-management-2025-06-27 beta header, offers a clear_tool_uses_20250919 strategy that "automatically clears the oldest tool results in chronological order" once input tokens pass your configured trigger, replacing each cleared result with placeholder text so the model knows something was removed. The documented example config keeps the three most recent tool uses. If your agent pulled visual evidence through a tool call, that evidence is in the same queue as everything else.

Images in Context Are Being Patched Weekly

This is live engineering, not settled behavior. Four releases in five days in November 2026 touched how images move through a Claude Code session, all quoted from the official changelog:

Pasting pixels puts you on the moving part of the system. A capture ID resolved over a local socket does not care which release you are on.

The Cost of Re-Pasting the Same Window

Anthropic's vision documentation gives the arithmetic directly: "Each patch is a 28×28-pixel block of the image, referred to as a visual token. An image, therefore, costs ⌈width / 28⌉ × ⌈height / 28⌉ visual tokens."

Run a normal Mac window through it. A 1512 by 982 capture is 54 by 36 patches, so 1,944 visual tokens. Share it again after the oldest-image sweep and that is 3,888. Share it twice more across a four-hour session and you are at 7,776 tokens spent on one window, with the earlier copies now placeholders.

Two more lines from the same page close off the obvious workarounds. Claude does not parse or receive any metadata from images passed to it, so the XMP payload inside your PNG never reaches the model through a paste. And on animation: "Animations are unsupported, and only the first frame is used." A GIF of a flickering layout bug arrives as one still frame.

That is the whole reason Stash composites the context banner onto the pixels. App name, window title, URL, OS version, display, timestamp, and the eight-character capture ID sit in a thin strip the vision model reads as text. The structured copy still lives in XMP for tools that read files, and the part a model can carry forward is the part printed on the image.

What an ID Resolves To

The ID is worth more than the image it came from. Hand #3F8A21C4 to Claude Code with the Stash MCP server connected and get_capture returns the dossier for that capture:

Four more tools sit alongside it. list_recent(n) returns about 100 tokens per capture, cheap enough for the agent to confirm it has the right one before committing to a dossier. search(query) covers app name, window title, bookmark name, text content and browser URL. get_bundle(id) returns a recording's markdown report, per-frame metadata and absolute paths to every asset. render_plain(id) gives a token-light text rendering for inline paste.

All five run over a Unix domain socket at ~/Library/Application Support/Stash/mcp.sock. No network call, no relay, nothing leaves the machine to answer the query. Every capture also carries a stash://bundle/<uuid> URI in its report front matter, under the versioned stash-1 protocol, so the reference holds after a restart.

Recordings follow the same rule. A five-minute session is capped at 30 interaction-anchored key frames with absolute paths rather than inlined images, so the agent opens the five to fifteen frames the timeline says matter. One real 5:30 session logged 2,222 interactions and came back as a 22 KB report, with scroll events aggregated into burst lines such as "29.7s to 30.1s, 74 scroll events."

Wiring It Up in Four Minutes

  1. Install Stash and run the MCP installer. One command from yourstash.ai/install configures Claude Code, Claude Desktop and Cursor.
  2. Capture with Command Control S. The banner is composited automatically. The eight characters at the end of it are the ID.
  3. Put the rule in your project-root CLAUDE.md. Something like: When I give you a Stash capture ID, call get_capture on it before answering, and call it again if you lose the image. That file is re-injected from disk after every compact, so the instruction outlives the thing it protects.
  4. After a compact, paste the ID, not the screenshot. Eight characters instead of 1,944 visual tokens, and the agent gets the accessibility tree and cursor position it never had from the pixels.

The hooks route automates step four if you would rather not think about it.

Where This Breaks

Four honest limits.


The Bottom Line

Treat visual evidence the way Claude Code already treats your files: as something with an address, fetched when needed. Compaction, per-request image limits, and API-side context editing all remove old images from what the model sees, and Anthropic's own documentation tells you the recovery path is to share the image again. An eight-character ID makes that recovery cost nothing and brings back more than the screenshot ever carried, because the accessibility tree, the cursor position and the window title were never in the pixels.

Download Stash for free, take one capture, and ask your agent to pull it by ID after your next compact.


Frequently Asked Questions

Does Claude Code keep my screenshots after a compact?

No. The context-window documentation lists what survives a compaction, and pasted images are not on it: the system prompt, project-root CLAUDE.md re-injected from disk, auto memory, the plan from plan mode, invoked skill bodies, and up to five recently modified files re-read from disk. The prompt-caching page is blunter about request-level image limits. Once Claude Code drops the oldest images, Claude can no longer see them and you have to share them again.

Why does my agent describe a screenshot it can no longer see?

Because the summary kept your words about the image and the image itself went away. Summaries are text, so the description survives and the pixels do not. The model then reasons from its own earlier prose, which is how a session that was accurate at hour one produces a confident wrong answer at hour three.

How many tokens does a screenshot cost every time I paste it?

Anthropic's vision documentation gives the formula as the ceiling of width over 28 times the ceiling of height over 28, in visual tokens. A 1512 by 982 window capture works out to 54 by 36, or 1,944 visual tokens. Paste the same window four times across a long session and you have spent 7,776 tokens on one piece of evidence. An eight-character capture ID costs a handful of tokens and resolves to more data than the image held.

Does Claude read the XMP metadata inside my PNG?

No. Anthropic's vision documentation states that Claude does not parse or receive any metadata from images passed to it. That is why Stash composites the context banner onto the pixels, where a vision model reads it as text, and keeps the structured copy in XMP for tools that read the file from disk. The banner carries app name, window title, URL, OS version, display, timestamp and the capture ID.

Will a Stash capture ID still resolve after the session compacts?

Yes, and after a restart. The ID points at a bundle on your Mac and the Stash MCP server resolves it over a local Unix socket, so it behaves like a file path rather than a message in the conversation. Each capture also carries a stash://bundle/<uuid> URI in its report front matter. The exception is the sensitive fields, which purge 24 hours after capture by default, so an older ID returns the screenshot and its basic metadata without the accessibility tree.

Can I just turn auto-compaction off instead?

You can move the line, not erase it. Claude Code's model configuration docs cover setting an auto-compact window, and CLAUDE_CODE_DISABLE_1M_CONTEXT=1 pins sessions to a 200K window, where they stop with a context-limit error instead of compacting. Per-request image limits are a separate mechanism from compaction, so an image-heavy session still loses its oldest screenshots either way.

Does a GIF hold up better than a PNG?

No. The vision docs support JPEG, PNG, GIF and WebP, then add that "Animations are unsupported, and only the first frame is used." A GIF of a flickering layout bug reaches the model as a single still. Stash recordings instead ship a markdown capture report with the full interaction timeline plus labeled key frames the agent reads by path, which is what makes a moving bug legible to an agent at all.