English · 简体中文

A Claude Code skill that gives vision capability to models with no native vision support (e.g. DeepSeek). It sends your image to an external vision model (default agnes-2.5-flash, OpenAI-compatible) and returns a text description — no Read tool needed, no third-party Python deps.

Features

• 🎯 Zero dependencies — Python 3.9+ standard library only, no pip install
• 🌍 Cross-platform — Windows / Linux / macOS / fish
• 🚀 Regional endpoints auto-selected — apihub .com (global) vs .cn (China), whichever is faster
• 🌐 Bilingual — UI auto-switches English/Chinese by system language (VISION_LANG to force)
• 🔐 Key safety — API key lives only in environment variables, never in project files
• 🧠 Thinking-model aware — auto-extracts the final answer from reasoning_content
• 🆓 Free vision model — default agnes-2.5-flash is free and unlimited (see Agnes docs); only rate limits apply
• 🖼️ Multi-image, OCR, screenshots, charts, QR codes — anything you need to "see"

Quick install

Option A: npx (one command)

# user-level (all projects)
npx vision-bridge-skill

# project-level (current project only)
npx vision-bridge-skill --project

Restart Claude Code (or start a new session). The skill will be auto-discovered.

npx requires Node.js (already present if you run Claude Code).

Option B: git clone (manual)

git clone https://github.com/cassanX/vision-bridge-skill.git
cp -r vision-bridge-skill/vision-bridge ~/.claude/skills/vision-bridge   # Linux/macOS
# Windows PowerShell:
# Copy-Item -Recurse vision-bridge-skill\vision-bridge $HOME\.claude\skills\vision-bridge

First-use configuration

The script asks once to configure the vision API; after that it never asks again.

You need a vision model API key (default agnes). Get one at the Agnes AI platform (email only, no card). Then configure one of two ways:

• A. Give the key to Claude — paste it into the chat; the agent will save it for you.
• B. Configure yourself — run the command below, replacing the placeholder:

python vision-bridge.py config "your-vision-api-key"

Restart the terminal, then send an image.

Usage

# Recognize a local image
python vision-bridge.py "photo.png" "Describe this image"

# Recognize a remote image
python vision-bridge.py --url "https://example.com/a.png" "Extract the text"

# Multiple images + prompt
python vision-bridge.py "img1.png" "img2.png" "Compare these two"

# Raw JSON output
python vision-bridge.py --json "photo.png" "Describe"

| Mode | Command | |---|---| | Check config | python vision-bridge.py check | | Configure | python vision-bridge.py config "<key>" | | Pin region | python vision-bridge.py config --region china\|global "<key>" |

Options: --model <model>, --max-tokens <n>, --temperature <0~2>, --json.

Regional endpoints

An apihub API key works on both endpoints; the script picks the faster one by system language (VISION_BASE_URL overrides):

| Region | Base URL | Best for | |---|---|---| | Global | https://apihub.agnes-ai.com/v1 | Users outside mainland China | | China | https://api.agnes-ai.cn/v1 | Users in mainland China |

Pin a region explicitly (e.g. a Chinese user on an English system, or a VPN user):

python vision-bridge.py config --region china "your-key"

Environment variables

| Variable | Purpose | Default | |---|---|---| | VISION_API_KEY | Your vision model API key | (required) | | VISION_BASE_URL | OpenAI-compatible base URL | auto by region | | VISION_MODEL | Vision model name | agnes-2.5-flash | | VISION_LANG | Force UI language: zh or en | auto-detect |

Troubleshooting

| Error | Meaning | Fix | |---|---|---| | 401 | Bad/expired key | Reconfigure: config "<key>"; ensure the key matches the base URL platform | | 404 | Wrong model or API URL | Check VISION_MODEL / VISION_BASE_URL | | 429 | Rate limited | Wait and retry; check quota | | Timeout | Thinking model is slow (10–90 s) | Timeout is already 120 s; use a faster model via VISION_MODEL | | Garbled Chinese in cmd | Console encoding | The script forces UTF-8 internally; set chcp 65001 in cmd if needed |

How it works

image → base64 → OpenAI Chat Completions (image_url) → external vision model → text

The API key is read from environment variables only (registry / rc files, cross-platform), written via config, never stored in the repo.

The bundled script is also usable standalone — see vision-bridge/scripts/vision-bridge.py --help.

License

MIT © cassanX