Can Claude Code See Images?
Short answer: no. Claude Code runs in your terminal. It reads text, generates code, and executes commands. It cannot open a screenshot, analyze a diagram, or understand a visual layout without help.
This is a real problem. You are staring at a UI bug. The button is offset by 5 pixels. The color is wrong. The layout breaks on mobile. You know exactly what the issue looks like. But Claude Code does not. You have to describe it in words, and the AI guesses.
There is a fix. claude-vision-skill adds image recognition to Claude Code. You drop an image into the conversation, and the AI processes it automatically. No model switching, no expensive multimodal API for everyday tasks.
GitHub Repository | 255 stars | 12 forks
The Problem: Terminal AI Cannot See
Claude Code excels at code generation, debugging, and refactoring. But it operates in a text-only terminal. It has no eyes.
When you encounter a visual problem, you have two bad options:
- Describe it in words. “The button on the right side is about 5 pixels too low and the color seems off.” The AI guesses. You go back and forth. Frustration builds.
- Copy-paste error messages. This works for text-based errors but fails completely for layout issues, design problems, or visual bugs.
The gap is real. Every frontend developer has hit this wall. You see the problem instantly. Your AI assistant is blind.
What claude-vision-skill Does
The tool bridges your terminal and visual content. Here is how it works:
- You send an image in the Claude Code conversation
- A script called
vision.jsreads the image file - The script converts it to base64 encoding
- It sends the encoded image to a vision API (Alibaba, OpenAI, or self-hosted)
- The API returns a text description of the image
- The description appears in your conversation
Claude Code then uses that description to understand what you are showing it. It can debug the issue, suggest fixes, or write code based on what it sees.
No manual commands. Once configured, you just send images and the AI handles the rest.
How to Pass Images to Claude Code
This is the part most developers get stuck on. The answer depends on your setup.
What works
File path method. Save the image to your project directory, then tell Claude Code to read it:
Look at this screenshot: ./screenshot.pngThe vision script reads the file, processes it through the API, and returns a description. Claude Code then understands the visual content.
Base64 in conversation. Some setups allow you to paste base64-encoded images directly. The vision script handles the conversion automatically.
What does not work
Ctrl+V in terminal. Most terminal emulators do not support image paste. Even if they did, Claude Code’s text interface cannot process raw image data.
Drag and drop. Terminal applications generally do not accept file drops. This is a limitation of the terminal itself, not Claude Code.
Native multimodal input. Claude Code does not have built-in vision. Unlike ChatGPT or Gemini, it cannot accept images in the conversation directly.
The workaround
claude-vision-skill is the workaround. It adds an external vision pipeline that Claude Code can use. The AI does not see the image directly. Instead, it reads a text description generated by a vision API. This description is usually detailed enough for debugging, code generation, and analysis.
The zero-setup workaround
You do not need an API key or a skill to get started. Any web-based AI with vision can describe your image, and you paste the description into Claude Code.
Here is the workflow:
- Open ChatGPT, Gemini, or Claude in your browser
- Upload your screenshot or image
- Ask it to describe what it sees (e.g., “Describe this UI layout in detail, including colors, spacing, and any issues you notice”)
- Copy the response
- Paste it into Claude Code
Here is a description of my UI issue:
[paste the description from ChatGPT/Gemini]
Fix the CSS to correct this layout problem.This works because Claude Code does not need to see the image itself. It needs a detailed text description of the visual content. A browser-based AI with vision gives you that description for free, with no API keys, no skills, and no configuration.
The limitation is that you are switching between tools. For a quick debug, it is fine. For repeated use, the skill-based approach is faster.
Setup Guide
Prerequisites
- Claude Code installed (installation guide)
- A vision API key (Alibaba Cloud Bailian, OpenAI, or self-hosted)
- Basic command line knowledge
Method A: Automatic Setup (Recommended)
The fastest path. Claude Code handles the configuration for you.
Step 1: Clone the repository
git clone https://github.com/asuojun/claude-vision-skill.gitStep 2: Ask Claude Code to configure it
Open Claude Code and paste:
Read the claude-vision-skill README and help me configure vision support.Claude Code will ask for your preferred vision service, API key, and model name. It handles file placement and configuration automatically.
Method B: Manual Setup
For full control over the process.
Step 1: Copy vision.js to your project root
Place vision.js in your project’s root directory.
Step 2: Configure your API credentials
Open vision.js and replace the placeholders:
// Replace these values
const API_KEY = "sk-xxx"; // Your actual API key
const MODEL = "xxx"; // Model name, e.g., "qwen-vl-max"
const BASE_URL = "xxx"; // API endpoint (keep default for Qwen)For Alibaba Cloud Bailian, the default BASE_URL points to the correct endpoint. Only fill in API_KEY and MODEL.
For OpenAI, change BASE_URL to:
https://api.openai.com/v1Step 3: Copy CLAUDE.md to your project root
Place CLAUDE.md alongside vision.js. This file tells Claude Code when and how to invoke the vision script. For more on writing effective Claude.md files, see the Claude.md guide.
Step 4: Test it
Send an image in your Claude Code conversation. If configured correctly, the AI processes the image and describes its contents.
Choosing a Vision API
You have three main options. The right one depends on your language preference, budget, and payment access.
| Provider | Model | Cost | Best For |
|---|---|---|---|
| Alibaba Cloud Bailian | qwen3.5-omni-plus | Free tier (1M tokens), then ~0.02 yuan/request | Budget-friendly, Chinese documentation |
| OpenAI | gpt-4o-mini | Standard API pricing | English language, international payment |
| Self-hosted | Any OpenAI-compatible model | Varies | Full control, privacy |
Alibaba Cloud Bailian (Recommended)
New accounts get 1 million free tokens. That is enough for months of regular use. After that, requests cost about 0.02 yuan each. The qwen3.5-omni-plus model handles documents and screenshots well.
OpenAI GPT-4o
Strong English-language image understanding. The catch: you need an international payment method. Use gpt-4o-mini to keep costs down.
Self-hosted
Set a custom BASE_URL and model name in vision.js. Any OpenAI-compatible endpoint works. You get full control, but you handle setup and maintenance.
Real-World Workflow: Debugging a UI Bug
Here is what the workflow looks like in practice.
Without vision:
- You see the button is misaligned
- You describe it: “The submit button on the contact form is 5 pixels too low and the padding looks wrong”
- Claude Code guesses based on your description
- You go back and forth three times before it gets it right
With vision:
- You take a screenshot of the bug
- You send it in Claude Code:
Look at this screenshot: ./bug.png - The vision script processes the image
- Claude Code reads the description: “The submit button is vertically offset. The container padding is inconsistent.”
- Claude Code suggests the exact CSS fix
One round trip instead of three. The AI sees what you see.
Troubleshooting
Image not being recognized
- Verify
vision.jsis in the project root - Check that
CLAUDE.mdis also in the project root - Confirm your API key is valid and has remaining credits
API errors or timeouts
- Test your API key directly with a curl request first
- Ensure
BASE_URLincludes/v1if your provider requires it - Check network connectivity to the vision API endpoint
Wrong or empty descriptions
- Try a different vision model (e.g., switch from
qwen-vl-maxtoqwen3.5-omni-plus) - Some models perform better on certain image types (documents vs. photos vs. screenshots)
FAQ
Does this work with DeepSeek?
Yes. claude-vision-skill was originally built for models like DeepSeek that lack native vision. It works with any AI assistant that can execute scripts. For more on using DeepSeek with Claude Code, see the DeepSeek setup guide.
Can I use my own vision model?
Yes. Set a custom BASE_URL and model name in vision.js. Any OpenAI-compatible vision API works.
Is there a cost?
Alibaba Cloud Bailian offers 1 million free tokens for new users. After that, requests cost approximately 0.02 yuan each. OpenAI charges standard API rates.
Does this affect code generation?
No. The vision feature operates independently. The AI uses your chosen model for code tasks and the vision API only for image processing.
What image formats are supported?
PNG, JPG, JPEG, WebP, and GIF. The vision API processes them all. For best results, use PNG or JPG screenshots.
Conclusion
Claude Code cannot see images. That is a limitation of running in a terminal. claude-vision-skill fixes it by adding an external vision pipeline that processes images through a vision API and returns text descriptions to your conversation.
Setup takes about five minutes. After that, you can debug UI issues from screenshots, read architecture diagrams, and process visual content without leaving the terminal.
If you have not set up Claude Code yet, start with the installation guide. For cheaper API access, check the DeepSeek integration. And if you want to write better project instructions, see the Claude.md guide.
Quick links:
- GitHub Repository
- Install Claude Code first
- Use DeepSeek as a cheaper alternative
- Write effective Claude.md files
- Codex Product Design Plugin Guide - Bridge Figma designs to code with AI
