Rich Context: @ References, Images, and Piped Data

Context Claude Cannot Infer

Claude Code can read your codebase, run commands, and discover context on its own. But there are times when giving Claude specific context upfront — before it starts working — produces better results than letting it explore freely. A screenshot of the bug you are trying to fix. The error log from the failing CI run. The specific file you want Claude to study before making changes. Providing this context directly saves exploration time and ensures Claude is working from the right starting point.

This lesson covers the mechanisms for providing rich context in your prompts: @ references, pasted images, piped data, and documentation URLs.

@ File References in Prompts

In CLAUDE.md files, @path imports include file contents at load time. In prompts during a conversation, @ references work slightly differently: when you type @src/api/handlers/users.ts in a message, Claude reads that file before formulating its response.

This is more reliable than describing what is in the file or pasting the contents yourself. Claude gets the file with full path context, which means it can navigate to related files and make cross-references. If the file imports from other modules, Claude can follow those imports. If the file has a counterpart in a test directory, Claude can find it. A @reference is a starting point for exploration, not just a content dump.

Use @ references in prompts when you want Claude to work from a specific file without first conducting a broad codebase exploration. It is especially useful when you know exactly which file is relevant and want Claude to start there rather than searching.

Images and Visual Context

Claude Code supports visual context directly in the conversation. Copy an image to your clipboard and paste it, or drag and drop an image file into the prompt input. Claude will read it as visual context and incorporate it into its response.

Visual context is particularly useful for:

• UI bug reports — paste a screenshot showing the broken layout
• Design implementation — paste a design mockup and ask Claude to implement it
• Comparison verification — ask Claude to take a screenshot of its implementation and compare it to the original design
• Error dialog capture — paste a screenshot of an error message when the text is hard to copy

The comparison workflow is especially powerful: "implement this design [paste mockup], take a screenshot of the result, compare it to the original, list the differences, and fix them." This creates a verification loop that does not require you to review every intermediate state.

Piping Data with stdin

For batch operations and scripted workflows, you can pipe content directly to Claude Code from the command line without opening an interactive session:

cat error.log | claude -p "Analyze this log and identify the root cause of the recurring 500 errors"
git diff | claude -p "Review these changes and identify any obvious bugs before I commit"
cat failing-tests.txt | claude -p "These tests are failing. Diagnose and fix the underlying issue"

The content of the pipe becomes part of the prompt, giving Claude the data it needs to work without requiring you to copy and paste or provide a file path. This integrates cleanly into shell scripts and CI workflows where you want Claude to analyze or process output from other commands.

URLs and Documentation

When a task requires knowledge from external documentation, provide the URL rather than summarizing the documentation yourself. Claude can fetch the page and read it. Use /permissions to allowlist domains you reference frequently — fetching from allowlisted domains does not require a permission prompt on each use.

URLs are especially useful for:

• API references for third-party services you are integrating
• Documentation for frameworks or libraries Claude may not know in detail
• RFC or specification documents that define behavior Claude should follow

Letting Claude Pull Its Own Context

Not all context needs to be provided upfront. For exploratory tasks, letting Claude discover what it needs is often more effective than front-loading specific files. Claude can use Bash commands, the gh CLI, file reads, and MCP tools to gather context as it works. "Use gh issue view 1234 to get the issue details, then read the relevant files and implement a fix" tells Claude where to start without prescribing every source it should read.

This approach also scales better: Claude discovers information that is actually relevant to the specific task, rather than reading everything you thought might be relevant and accumulating context it will not use.

Front-Load vs Discover: When to Choose Which

The choice between providing context upfront and letting Claude discover it comes down to how well-defined the task is.

Front-load context when you know exactly which file, which error, or which design constraint is relevant and you want Claude to start from that point immediately. This avoids unnecessary exploration and gets to implementation faster. Debugging a specific error, implementing a specific design, working with a specific file — these are front-loading candidates.

Let Claude discover when the task is exploratory, you are not sure which files are relevant, or you want Claude to find context you might not have thought to provide. Investigating an unfamiliar bug, understanding how an unknown part of the codebase works, or exploring what needs to change to support a new feature — these are discovery candidates. Use --add-dir to give Claude access to additional directories beyond the main working directory when the relevant code spans multiple repositories.