Claude Code Context: What the Agent Actually Sees

Claude Code context is everything the terminal agent can attend to in this turn: the system prompt, your messages, files it read, tool results, memory files, and images. It is not magic awareness of your screen. If you did not put the control in that window, Claude Code does not know the control.

People treat "add more context" as "paste more." That is how you hit the cap with a 5K PNG and still watch it edit the wrong button. How to give Claude Code context is the practical checklist. This post is the engineering of the window.

What fills Claude Code context, in order?

Think in layers. Each layer is useful until it is noise.

System and tool schemas. Always there. MCP tools add more schema. A dozen servers spend tokens before you say hello.

Repo guidance. CLAUDE.md and rules you configured. Durable facts belong here: how to run tests, which package manager, the design token file. Not "the button is broken today."

Conversation. Your prompts and its replies. Long debates about taste crowd out the file it needs.

Tool results. Read, Bash, search, MCP. This is the honest working set. A 40,000-character window dump can be right or it can be a novel.

Images. Screenshots are expensive. See screenshots waste Claude Code tokens. A crop is cheaper than a desktop.

Cursor users know the same pain as context used. The product UI differs. The math does not.

How do I give Claude Code context for a UI bug?

Do not start with a screenshot. Start with an identity.

If you know the file. Mention the component path. Say the prop. Done.

If you only know the pixels. Capture the live UI. Resolve the Accessibility element: role, label, frame, parent chain, confidence, circled-versus-dwelled. Bind "this" to the pointer at the moment you said it.

Then add a crop. Evidence, not the payload.

Then add window text if the copy is the bug. PinVari reads up to 40,000 characters from the focused window, including text scrolled out of view, plus an interactive-element map and the real URL from AXWebArea.

Connect the local server. PinVari, Connect, Claude Code, or:

claude mcp add --scope user pinvari -- "$HOME/.pinvari/mcp/pinvari-mcp"

Never the bare claude mcp add pinvari. The app must be running on 127.0.0.1:3402.

The agent calls pinvari_next_instruction. That tool result is Claude Code context, structured. When it is finished, pinvari_mark_done. If it is lost, pinvari_request_capture lights the notch island and you point again.

Use Option-Command-A to mark, Option-Command-V for voice-only, Option-Command-P to pause on a scrolling page. Freehand marks. Multiple regions. On-device speech and OCR.

What should not go into Claude Code context?

Whole monorepos. Search, then read the file. Do not concatenate the company.

Yesterday's thread. Compact or start a new session when the task changes. Old CSS arguments will steer a backend bug.

Production dumps. Redact. Crop. On-device capture should not upload by default; your model call still might. Treat tool results as prompt data.

Every MCP server you have ever installed. Disable the ones this task does not need. Schema is context.

Four-column tables of maybe related files. Give one path.

Full-page marketing screenshots. If the bug is a checkbox, the hero image is vandalism.

Claude Code memory versus this-session context

Memory files persist. Session context dies when the chat dies.

Put invariants in CLAUDE.md: package manager, generated folders you never edit, where UI copy lives.

Put incidents in the session: this capture, this stack trace, this failing test.

If you promote a one-off bug into memory, the agent will keep fighting a button you shipped last week.

I keep memory short enough to read on a phone. If it scrolls, it is a wiki, and Claude Code context will pay for it every turn.

A context budget I actually use

About 10 percent instructions and CLAUDE.md.

About 40 percent files the agent opened because it had a path.

About 20 percent tests and logs for the failing case.

About 20 percent one capture bundle (name, words, crop, URL).

About 10 percent slack for its plan.

Those are not measured percents from Anthropic. They are a habit. When a session feels drunk, I look at images and old tool results first.

How MCP changes the context story

MCP is not extra intelligence. It is extra inputs with names.

A filesystem server can waste context by dumping directories. A screen-context server can save it by returning one element.

PinVari tools (pinvari_get_capture, pinvari_list_captures, pinvari_get_frame, pinvari_health) let the agent pull only what it needs. The Command Center keeps the rest on disk, grouped by app, with crash-safe recovery.

Multi-display marks store which monitor they were drawn on. Electron and Chromium get AXManualAccessibility and a short retry. Bare AXGroup walks to a labeled descendant. Canvas falls back to Vision OCR and says so.

That honesty belongs in the tool result. It is better Claude Code context than a confident lie.

The Mac app is a one-time launch license. You still pay the model. Spend fewer tokens on pixels.

Debugging when it lost the context

It never had it. You described a modal it never read. Capture or mention the file.

It had it and you buried it. The last three tools were searches over node_modules. Start a new session, replay the capture.

The image decoded wrong. Dense toolbars. Named element time.

The URL was in your head. Put the AXWebArea URL in the bundle.

Permissions. Accessibility off means empty names and a pretty crop. Grant TCC. A new binary path looks like a new app.

I do not trust a remembered button across a compact. Recapture. It is ten seconds.

How do I watch Claude Code context without a vendor dashboard?

You watch what it cites.

If the next edit is in a file it never read, the window did not contain the path. Mention the file or recapture the UI so the name can be searched.

If it cites a screenshot and the wrong icon, the image ate the budget and still lost. Replace the image with an AX name.

If it cites CLAUDE.md for a one-off bug, you promoted junk to memory. Cut that paragraph.

I say the budget out loud at the start of a hard session: "one capture, two files, one test." When I break that, Claude Code context feels haunted and I start a new session.

Cite or it is not in context is a rude rule that works.

The same rule applies after a compact. Assume the crop is gone. Pull the capture again. Ten seconds is cheaper than a wrong PR.

Should I use images in Claude Code context at all?

Yes, for visual bugs you cannot name: a 2-pixel gap, a wrong shadow, a clipped glyph.

No, for "click the button." The button has a name. Use it.

One small crop plus a sentence is the only image pattern I keep. A second image waits until the first fix lands. That discipline is most of Claude Code context hygiene.

FAQ

How much Claude Code context do I get?

The window depends on the model and the product default that week. Treat it as finite. Watch for summarization or dropped files when sessions get long. I will not invent a token number.

Is CLAUDE.md part of Claude Code context every turn?

If the product injects it, yes, which is why you keep it short. A 2,000-line CLAUDE.md is a tax on every bug.

Should I paste the whole ticket into Claude Code?

Paste the executable part: element, steps, expected, actual, crop. Not the political thread. Jira novels evict code.

Does MCP use extra Claude Code context?

Yes, tool schemas and tool results both count. A small, high-signal server is cheaper than three exploratory reads and a desktop PNG.

Can Claude Code see my screen without a tool?

No. It sees the terminal, the files it opened, and what you pasted. Screen awareness is a local capture tool plus MCP, or an image you attached on purpose.

How do I reset context without losing the bug?

Keep the capture in the Command Center. New session. Pull pinvari_next_instruction or the same crop plus name. Do not reload the Slack archaeology.