Skip to content

About

a skill give text-only agents image understanding through a vision-capable OpenAI-compatible Chat Completions API

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Vision Bridge Skill

License: MIT

English | 简体中文

Vision Bridge gives text-only Agents image understanding through a vision-capable OpenAI-compatible Chat Completions API. It supports OCR, screenshot troubleshooting, chart analysis, and general image understanding.

OpenAI-compatible only describes the API format. The selected model must also support image_url input.

Project structure

vision-bridge-skill/
├── SKILL.md
├── scripts/
│   └── vision.js
├── references/
│   └── configuration.md
├── test/
│   └── vision.test.js
├── .github/workflows/ci.yml
├── .env.example
├── .gitignore
├── LICENSE
├── package.json
├── README.md
└── README_zh.md

Installation

Claude Code

git clone https://github.com/asuojun/vision-bridge-skill.git \
  ~/.claude/skills/vision-bridge

Codex and other SKILL.md-compatible Agents

Place the repository in the Agent's Skill search directory and keep SKILL.md at the repository root. Some Codex environments use:

git clone https://github.com/asuojun/vision-bridge-skill.git \
  ~/.codex/skills/vision-bridge

Configuration

Copy the example configuration:

cp .env.example .env

Set your provider details:

OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://provider.example/v1
VISION_MODEL=your-vision-capable-model

For a no-auth local service, omit OPENAI_API_KEY:

OPENAI_BASE_URL=http://127.0.0.1:8000/v1
VISION_MODEL=local-vlm

The script only loads .env from the Skill root automatically. To use another file, set it explicitly:

export VISION_ENV_FILE=/absolute/path/to/vision.env

See references/configuration.md for all options.

Usage

Analyze a local screenshot:

node scripts/vision.js ./screenshot.png \
  "Identify the visible error and suggest troubleshooting steps"

Analyze a remote image:

node scripts/vision.js https://example.com/chart.png \
  "Summarize the chart's trends and anomalies"

Run high-detail OCR:

node scripts/vision.js --detail high ./scan.jpg \
  --prompt "Transcribe every visible line and mark uncertain characters as [?]"

Return JSON:

node scripts/vision.js --json ./image.png "Describe the image"

Show all CLI options:

node scripts/vision.js --help

API compatibility

The provider must support:

  1. POST /chat/completions
  2. OpenAI-style model and messages
  3. array-form messages[].content
  4. text and image_url content parts
  5. image URLs or base64 data URLs
  6. responses at choices[0].message.content

Some models use max_completion_tokens instead of max_tokens:

export VISION_MAX_TOKENS_FIELD=max_completion_tokens

If the provider rejects the optional detail field:

export VISION_DETAIL=none

Privacy

Images are sent to the configured vision API. Before sending identity documents, credential screenshots, customer data, internal systems, or other sensitive content, confirm that the user has authorized the provider to process that data.

The script does not scan directories and does not automatically load .env files from the current working directory. Never commit API keys or include them in Issues, logs, or screenshots.

Testing

Node.js 18 or newer is required:

npm install
npm run ci

Tests use a local mock server and never call a real vision API.

License

MIT

About

a skill give text-only agents image understanding through a vision-capable OpenAI-compatible Chat Completions API

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages