Give Claude Code Subagents a Capture ID, Not a Screenshot

Paste the ID

Every Stash screenshot carries an eight-character capture ID in its banner. Something like #7F3A9C21. Put that string in the prompt you hand a subagent and the subagent resolves it over MCP:

Review the layout in Stash capture #7F3A9C21 against
docs/design/spec.md. Call mcp__stash__get_capture first.

The subagent gets the app name, the bundle ID, the window title, the browser URL if there was one, the macOS version, the display resolution and scale factor, the light or dark appearance, the active file path and cursor position if it was an editor, the full accessibility tree of that window, and the arrows and rectangles you drew as geometric shapes rather than baked pixels. None of it enters your main conversation. You paste 40 characters, not a megabyte.

This is worth doing because of what a subagent actually is.

What a Subagent Inherits

The Claude Code documentation is specific:

"Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions."

Its own context window. So the screenshot you pasted three turns ago upstream is not in it. The subagent starts with the prompt text you hand it and nothing else from your conversation.

Tools work differently. Per the same docs, subagents inherit the built-in tools and MCP tools from the main conversation, then two filters narrow that pool. The second filter is the interesting one for anyone shipping visual work to agents:

"Apart from Agent and ExitPlanMode, which follow the first filter's conditions wherever the subagent runs, a background subagent keeps every MCP tool but only these built-in tools: Read, Grep, Glob, Bash, PowerShell, Edit, Write, NotebookEdit, WebFetch, WebSearch, TodoWrite, Skill, ToolSearch, EnterWorktree, ExitWorktree, Monitor, TaskStop, SendMessage, and Artifact."

Background is the default as of Claude Code v2.1.198. So the tool channel that survives the trimming, unchanged, is MCP. That is the channel to build on.

The same reasoning applies one level up. Claude Code now ships background agents and agent teams, where several sessions run at once and report to one place. Every one of those has its own window too.

The Token Math on Re-Pasting

Re-pasting the image into each subagent works. It is just expensive, and the cost is documented precisely. Claude views images in 28x28 pixel patches, so an image costs ⌈width / 28⌉ × ⌈height / 28⌉ visual tokens. Anthropic publishes the table:

Those are the high-resolution tier numbers, which apply to Claude 4.7 and later models. Anthropic's own note: "High-resolution images can use up to roughly three times more visual tokens than the same image on a standard-tier model." At Claude Opus 5's $5 per million input tokens, the docs put a 4K image at about $23.92 per thousand.

Now fan out. Five subagents reviewing one 4K capture is 23,920 visual tokens spent before any of them has reasoned about anything. Run that loop thirty times in a day and you are paying for 3.6 million visual tokens of the same handful of screens.

A Stash accessibility tree for a typical app window runs 1 to 5 KB of structured text, roughly 250 to 1,200 tokens. It carries pristine button labels, text field contents, and menu items instead of an OCR guess at them. Ten of those cost less than one 4K image, and they are the part the model was going to try to extract from the pixels anyway.

The image is still there if an agent wants it. get_capture and get_bundle return absolute file paths, so a subagent pulls the actual picture into context only when it decides it needs to look.

Claude Does Not Read Image Metadata

From the FAQ in Anthropic's vision documentation, verbatim:

Does Claude read image metadata? "No, Claude does not parse or receive any metadata from images passed to it."

That one line settles a design question. You cannot embed context in a PNG and expect a pasted image to carry it. EXIF, XMP, sidecars, all of it is dropped at the door.

So Stash does two things instead. The context banner is composited into the pixels, where the model reads it as ordinary text in the image. And the structured payload, the XMP fields and the accessibility tree and the dev context, is served over MCP where it is text from the start and never had to survive an upload.

The capture ID is the hinge between the two. It is printed in the banner, so an agent looking at the pasted picture can read the ID and then go fetch everything the picture could not carry. A human reading the same screenshot in Slack can do it too.

What Comes Back

Stash exposes five MCP tools on a local server. They are built to be called in that order: triage cheap, fetch once.

A screen recording is where the gap gets wide. No model reads an MP4. A Stash recording ships a markdown report of the session instead: every click with pixel coordinates, drag endpoints, scroll bursts aggregated so 2,000 raw events collapse into about 20 lines, keyboard input with modifiers, every clipboard copy with the literal text you copied, app and window focus transitions, voice transcript inline with timestamps, and up to 30 interaction-anchored key frames with their own timestamps. A 5:30 session with 2,222 interactions produces a roughly 22 KB report. That is a subagent's entire view of a bug reproduction for about 6,000 tokens, plus whatever frames it chooses to open.

Wiring It Up

The installer at yourstash.ai/install-claude.sh configures Claude Code, Claude Desktop, and Cursor in one command. Other MCP clients work through the same stdio bridge pointed at their config file.

Once the server is in your session config, every subagent that inherits MCP tools can reach it. To scope it to one subagent instead, use the mcpServers frontmatter field:

---
name: ui-reviewer
description: Reviews Stash captures against the design spec
disallowedTools: Write, Edit
mcpServers:
  - stash
---
Resolve the capture ID in the prompt with get_capture before
looking at anything else. Read the accessibility tree for
element labels rather than guessing from the image. Only open
the screenshot file if the tree leaves something ambiguous.

Note the disallowedTools there. That is deliberate. The tools field is an allowlist, and Anthropic's own example spells out the consequence: a subagent limited to Read, Grep, Glob, and Bash "can't edit files, write files, or use any MCP tools." If you restrict with tools and forget to list your MCP entries, the capture ID in your prompt becomes a string the subagent cannot resolve, and it will happily reason without it. disallowedTools subtracts instead, and keeps the rest of the pool.

Both fields take server-level patterns, so mcp__stash grants or removes every Stash tool at once depending on which field it lands in.

Where This Breaks

Four honest limits.

Plugin subagents ignore the field. The docs state that plugin subagents do not support hooks, mcpServers, or permissionMode, and those fields are dropped when the agent loads. Copy the agent file into .claude/agents/ if you need them.

The socket is local, and that cuts both ways. Stash listens on a Unix domain socket at ~/Library/Application Support/Stash/mcp.sock. Nothing goes over the network, which is the point. It also means an agent running on another machine or in a cloud session cannot resolve a capture ID. IDs are good on the Mac that made them.

Sensitive fields expire. Accessibility trees, selected text, file paths, git branches, and terminal working directories purge 24 hours after capture by default. You can set that anywhere from one hour to never. An ID from last week still resolves to the screenshot and its basic metadata, but the tree may be gone, and a subagent will tell you it got a thinner payload than you expected.

Only approved clients connect. The server enforces a peer-auth allowlist configured in Settings. A new MCP client is not automatically trusted, which is correct and occasionally annoying the first time.

One more thing that is not a limit so much as a direction of travel. The Model Context Protocol shipped revision 2026-07-28 on July 28, which removes the initialize handshake and makes the protocol core stateless. Stateless means each connection carries no memory of the last one. A stable, addressable identifier for the thing you want stops being a convenience at that point and starts being the mechanism.

The Bottom Line

Screenshots are the wrong unit of exchange between you and a fleet of agents. They are expensive per read, they carry no metadata across the API boundary, and they do not cross a context window without being paid for again. An ID is cheap, it is text, it survives every filter Claude Code applies to a background subagent, and it resolves to more information than the picture ever held.

Capture with ⌘⌃S, read the eight characters off the banner, and hand those to whichever agent needs to see what you saw. Download Stash for free and the MCP server is wired into Claude Code and Cursor in one command.