Last updated 13 October 2026
Let Claude Code see local images
Communicating visual state to a terminal agent
Developers often hit a wall when a CSS layout breaks or a component renders incorrectly. You can see the overlap or the missing padding, but the claude command line interface exists in a text-based world. Passing a screenshot or a design mockup to the agent requires more than just dragging a file into the terminal window. You need a workflow that makes these binary files accessible to the agent tools without breaking the text-heavy flow of a coding session. This is common when you are trying to match a Figma export or fix a padding issue that only appears on specific screen sizes.
The agent cannot see your screen in real time, so you must provide it with the data it needs through the file system. When you describe a visual bug, the agent needs to verify your claims by looking at the actual output. This process involves capturing the visual state of your application and placing it where the agent tools can find it. By treating images as part of the project context, you turn a vague description of a UI bug into a concrete task that the agent can solve by analyzing pixels and code simultaneously.
Placing images within the project hierarchy
The agent relies on tools like Read and Glob to explore your codebase. It respects your .gitignore file, so any image you want the agent to see must be in a location it can reach. If you keep your screenshots in a directory outside the project root, the agent will not find them by default. Create a specific directory like docs/ui-feedback or tmp/screenshots within your repository. This ensures the agent can use the Read tool to access the image data when you reference the path in your prompt. You should avoid putting images in folders that are excluded by your global or project-level ignore rules.
Once the images are in the project tree, you can use the Glob tool to show the agent what is available. If you have multiple screenshots from different browsers, naming them clearly like mobile-safari-bug.png or desktop-chrome-header.png helps the agent pick the right file. The agent works best when it knows exactly which file corresponds to which visual state. Keeping these assets organized inside the project folder structure allows the agent to maintain a clear map of the visual evidence it needs to process to complete your request.
Referencing image paths in your prompts
When you start a session with the claude command, you can direct the agent to specific files immediately. If you have a screenshot of a rendering error at docs/bug-report.png, tell the agent to look at that file to understand the styling issue. The agent uses its internal vision capabilities to process the image once it accesses the file via the Read tool. You do not need a special command to trigger this visual analysis. Simply stating that the visual requirements are in a specific file path allows the agent to pull that context into the conversation and compare it against your existing CSS or HTML files.
Be specific about what the agent should look for in the image. Instead of saying the layout is broken, tell the agent to compare the screenshot at docs/design.png with the current implementation in your components folder. The agent can then use the Read tool on both the image and the source code to identify discrepancies. This direct reference method is the most efficient way to bridge the gap between your visual experience and the agent's text-based output. It allows for a loop of feedback where you provide a screenshot, the agent proposes a fix, and you provide a new screenshot of the result.
Managing visual tasks with adhdTerminal
Running multiple UI fixes simultaneously can lead to context switching fatigue for any developer. Using adhdTerminal allows you to dedicate specific tiles to different visual bugs on your wall. You can name one tile for a header layout issue and another for a mobile navigation bug, assigning each a unique color and number. Each tile maintains its own session history and file context. This setup lets you monitor the progress of visual analysis on one project while you handle logic changes in another. The visual indicators on the tile show you when the agent is working on a complex image analysis task or waiting for your input.
Since adhdTerminal is a native app for macOS and Windows, it provides a stable environment for these side-by-side sessions. Tiles reopen in the same place after a restart and resume the same session, which is vital when you are working through a long list of UI refinements. If you need to step away from your desk, the free iPhone app mirrors your wall over an end-to-end encrypted link. You can check if a visual task is done or send the next task to a specific tile from your phone. This continuity ensures that your visual debugging workflow remains uninterrupted even as you move between different environments.
Writing visual instructions in project files
Your CLAUDE.md file is the best place to define how the agent should handle visual assets across the entire project. Use this file to specify which directories contain design mockups or where the agent should look for reference screenshots. You can add a section in the root CLAUDE.md that instructs the agent to always check the design folder before suggesting CSS changes. This ensures that every time you run claude, the agent starts with the correct mental model of your project aesthetics and layout requirements. It prevents the agent from making guesses about colors or spacing that contradict your design system.
You can also use a CLAUDE.md file in a subdirectory to apply rules to specific parts of the tree. If you have a legacy component folder that requires strict adherence to old screenshots, put the instructions there. This localized context helps the agent understand that visual consistency in that directory is higher priority than modernizing the code. By documenting these visual dependencies in markdown, you create a persistent guide that the agent follows during every session, reducing the amount of repetitive prompting you have to do for every new UI task.
Managing permissions for image access
Claude Code operates under different permission modes like default, acceptEdits, or plan. If the agent needs to write a new image or modify a binary file, it will ask for your consent unless you are in bypassPermissions mode. You can cycle through these modes using Shift+Tab during an active session to adjust how much freedom the agent has. If you find the agent is restricted from reading certain directories where your images live, you should check your settings.json file. You can configure specific permissions for the Read tool under the permissions key to make the process more efficient.
Permissions are handled at the project level in .claude/settings.json or at the user level in ~/.claude/settings.json. If you are working with sensitive visual data, you can use these settings to ensure the agent only reads from specific allowed directories. This control is important for maintaining security while still giving the agent enough context to be useful. If the agent ever reports that it cannot access a screenshot, check your permissions configuration first to see if the tool has been explicitly denied access to that file type or path.
Monitoring long visual analysis sessions
Analyzing high-resolution images can take more time than processing simple text files. When the agent is using the Read tool on a large file, it may stay in a working state for several seconds. If you are using adhdTerminal, the tile on your wall will indicate this status clearly, allowing you to focus on other work while the agent processes the visual data. You can see the last exchanges of the conversation directly on the tile, which helps you understand if the agent has finished the analysis or if it has encountered an error. This visibility is especially helpful when dealing with complex UI audits.
If you need to stop the agent during a long image read, you can press the Escape key to interrupt the current action. If you feel the agent has gone down the wrong path with its visual interpretation, pressing Escape twice allows you to go back to earlier messages and rephrase your prompt. This granular control over the session history ensures that you do not waste time or cost on incorrect visual analysis. Once you find the right approach, the agent can proceed with the code changes based on its corrected understanding of the image.
Optimizing context with compact and clear
Image data can consume a significant portion of the context window because visual information is often more dense than text. After the agent has successfully analyzed a set of screenshots and provided the necessary code fixes, use the /compact command. This summarizes the session so far and frees up space, preventing the context window from becoming bloated with old image data that is no longer relevant. Summarization keeps the agent focused on the current state of the code rather than the bugs it has already fixed.
If the session becomes too cluttered with various visual trials or if you want to switch to a completely different UI task, the /clear command allows you to start over in the same folder. This is cleaner than quitting and restarting because it keeps you in the current environment while resetting the agent's memory. You can use /cost and /usage to monitor how much the visual analysis is costing you. Since image processing can be more expensive than text, keeping an eye on these stats helps you manage your project budget effectively while using the agent for heavy UI work.
Ensuring tool stability with doctor and update
Sometimes the agent might fail to process a specific image format or a very large file due to environment issues. If you notice that the Read tool is returning errors when accessing your local images, run the claude doctor command. This command checks your installation and configuration for common issues. It can help identify if there are system-level restrictions or missing dependencies preventing the agent from handling certain binary files. It is a good first step whenever the agent's behavior becomes unpredictable during a visual task.
Keeping your tool updated is also essential for visual tasks. Anthropic frequently improves the way the agent handles file context and tool interactions. Run the claude update command regularly to ensure you have the latest improvements for file handling. If you encounter a persistent problem with image reading that the doctor command cannot fix, check the /release-notes to see if there are known issues with the current version. Staying on the latest version ensures that you have the most reliable experience when asking the agent to help with your local UI styling and bug reports.
Questions people ask
How can I check if the agent successfully saw my image?
You can use the /status command to see the current state of the session and which files have been read into context. If the image path is listed or if the agent provides a detailed description of the UI in its next response, you know the Read tool worked correctly. If the agent seems confused, try explicitly asking it to describe the image it just read to verify its understanding.
What should I do if my images are too large for the agent to read?
If an image file is very large, the Read tool might fail or consume too much context. You should resize the screenshot to a lower resolution or convert it to a more efficient format like PNG or JPEG before placing it in your project folder. The agent does not need 4K resolution to understand a layout bug or identify a missing CSS property.
Can the agent save a new screenshot of its own work?
The agent can use the Write tool to create or modify files, but it does not have a native tool to take a screenshot of your running application. You must capture the screenshot yourself and place it in the project directory. Once you have saved the file, you can prompt the agent to use the Read tool to look at the results of the changes it just implemented.
Read next
- Add build instructions to your CLAUDE.md fileImprove project context by adding specific build commands and environment requirements to your CLAUDE.md file for the AI to follow.
- Add common error fixes to CLAUDE.mdImprove project memory by adding a section for common errors and their fixes to your CLAUDE.md configuration file.
- Add custom shell aliases for Claude CodeSpeed up your workflow by creating shell aliases for common Claude Code invocations and project-specific startup commands.
- Add test commands to a CLAUDE.md fileUnderstand how to define specific test runners and environment flags in your CLAUDE.md file so the tool runs the correct test suite.