@-Mentions, Multi-Dir & Image Hygiene

Claude Code works inside a fixed context window — 200K tokens (up to 1M in some configurations), of which only ~150–170K is usable after the system prompt, tool definitions, and CLAUDE.md. Everything Claude knows about your code at any moment is whatever has been read into that window. The window is a budget, and the single biggest lever you control is what you pull in and what you keep out.

There are two ways content lands in context, and confusing them causes real bugs:

• Pulling things in is deliberate and surgical. @-mentions read a specific file, directory listing, or MCP resource — exactly what you point at, nothing more.
• Things accumulating is passive and dangerous. Pasted screenshots, Chrome-MCP screenshots, and shell output pile up in the session transcript whether or not you still need them. Left unmanaged, that pile-up doesn't just slow Claude down — it can make a session impossible to resume.

CONTEXT WINDOW (a budget you spend by reading)
  pull IN  (deliberate)        keep OUT / manage (passive)
  ─────────────────────        ───────────────────────────
  @file  @dir  @mcp_resource    screenshots stored at full res
  Tab-complete after @          Chrome-MCP screenshots
  full file read into context   shell ! output
        │                              │
        ▼                              ▼
   precise, cheap if small        grows silently → 400 on resume

This lesson covers both halves: the precise syntax for pulling the right things in, and the hygiene for keeping the wrong things out before they break your session.

The @ prefix references something by path and reads it into context before Claude responds. There are three forms, and Tab completion works after you type @:

A few mechanics worth internalizing:

• Tab completes after @. Type @src/comp then press Tab to fill in the matching path — faster and less error-prone than typing the whole thing. You can drop several mentions in one prompt: Compare @src/old.ts with @src/new.ts and explain the regression.
• A file mention is a full read. @config/settings.json loads the entire file into context, not a summary or a slice. That is exactly what you want for a small config — and exactly what you must think twice about for a 5,000-line log (covered next).
• A directory mention is a listing, not a recursive read. @src/api shows Claude what's in that folder so it can decide what to open; it does not slurp every file. Use it to orient Claude, then let it (or you) @ the specific files that matter.
• MCP resources use a protocol URI. The form @mcp_resource:protocol://path reaches into a connected server. The available protocols depend on which MCP servers you've connected — check /mcp to see what's wired up.

By default Claude Code can only touch files under your current working directory. When a task spans repos — say your app needs to read a shared library two folders up — you extend the workspace to grant access to extra directories.

Both grant file access to the named directories for the session. One important limit: --add-dir grants access but does not discover those directories' own .claude/ configuration — their CLAUDE.md, settings, and skills are not loaded. You're adding files to reach, not adopting another project's setup.

There's a known, currently-live bug here you must work around:

Because the context window is a budget, the size of what you reference matters. A small config file costs almost nothing. A 5,000-line generated log, a giant lockfile, or a minified bundle can swallow a large chunk of usable context in a single @-mention — and once it's in, it competes with everything else for Claude's attention. Performance degrades as context fills: it's about quality, not just whether you hit the ceiling.

Practical habits:

• Reference narrowly. @-mention the specific file you mean, not a directory full of large files.
• Filter before you feed. For huge logs, don't @ the whole file — pipe a slice: tail -200 app.log | claude -p "find anomalies".
• Watch the meter. /context shows a colored breakdown of what's consuming the window; /usage shows session cost. Check them when a session feels sluggish.

That piping example exposes a subtle but critical distinction. There are two completely different ways to get content to Claude:

When you pipe, you are handing Claude a blob of text on standard input. If that text happens to name a file, Claude will not go open it unless you ask. Piping adds the bytes you piped; it does not trigger a file read.

Images are uniquely dangerous to context, and this is the part most users learn the hard way.

When you paste a screenshot (Cmd+V on macOS/iTerm2, Ctrl+V on Windows/Linux, Alt+V on WSL) it appears in the conversation as [Image #N]. What's not visible: that image is stored in the session's JSONL transcript at its original resolution. A few full-screen 4K screenshots are enormous. They don't compress, they don't shrink, and they don't go away on their own.

Two failure modes follow directly:

• Permanent 400 errors on resume (#34025). As images accumulate in the transcript, the stored payload grows. Eventually it exceeds what the API will accept, and every attempt to resume that session fails with a 400 error — permanently. The conversation is effectively bricked, because the offending data is baked into the saved transcript.
• Chrome-MCP screenshot token drain (#27869). If you use the Chrome integration / browser MCP, automated screenshots can be taken repeatedly and stored the same way, causing extreme token drain that burns through your context window fast.

The through-line: visual artifacts are heavy, they're stored verbatim, and they persist. Treat them as something you actively manage, not something the tool cleans up for you.

Knowing the trap, the discipline is simple: manage visual artifacts before they accumulate, and start fresh for image-heavy work.

Two commands are your tools here:

The playbook: if you're about to do a lot of visual work (mockup comparisons, browser screenshots, error captures), /clear first so you start with a clean transcript — and consider clearing again partway through. Don't let a 200-message debugging session full of 4K screenshots sit in the transcript until resume breaks. Clearing or compacting before resuming an image-heavy session is the cheap insurance against #34025.

Finally, a related context mechanic that's easy to misread — shell mode: