opencode-vision

Give non-vision opencode models (e.g. opencode/deepseek-v4-flash-free) the ability to see images and screenshots by routing them to a vision-capable model.

When a user attaches an image to a text-only model, opencode rejects it with this model does not support image input. This plugin registers a vision tool that resolves the image and sends it to a vision model, returning a detailed textual description the primary model can reason about.

How it works

user attaches screenshot
        |
        v
opencode rejects it: 'this model does not support image input'
        |
        v
injected system prompt tells the model to call `vision`
        |
        v
vision tool resolves the image:
  1. current session's attachments (via the opencode server API)
  2. opencode.db directly (SQLite, cross-session)
  3. filesystem search (~/Pictures/Screenshots, /tmp, ~/Downloads, cwd, ...)
        |
        v
spawns `opencode run -m opencode/mimo-v2.5-free -f <image>` (CLI fallback)
        |
        v
retries primary model up to 3 times (initial + 2 retries), then falls back
to `openrouter/xiaomi/mimo-v2.5` (configurable)
        |
        v
returns the textual description to the parent model

Install

Place vision.js in your plugin directory:

• Global: ~/.config/opencode/plugins/vision.js
• Project: .opencode/plugins/vision.js

Plugins in these directories load automatically at startup. Restart opencode.

Usage

Nothing to do — the model calls vision automatically when you attach an image. The tool accepts:

• filePath — absolute path or bare filename (e.g. Screenshot 2026-06-18 at 17.32.24.png). Omit to use the most recent attached image.
• question — the user's specific question about the image; the vision model answers it directly (and still transcribes the image).

Configuration

env var	default	description
SEE_IMAGE_MODEL	opencode/mimo-v2.5-free	Vision model ID used for the CLI call
SEE_IMAGE_FALLBACK_MODEL	openrouter/xiaomi/mimo-v2.5	Vision model used after the primary model fails 3 attempts (initial + 2 retries)
SEE_IMAGE_TIMEOUT	60000	Timeout in ms per CLI call

Features

• Resolution ladder: session parts → SQLite DB → filesystem search, with fuzzy filename matching (NFKC-normalized, U+202F handled)
• Vision-capability detection — instructions are only injected for models that lack native image input
• Retry with fallback: primary model is attempted up to 3 times (initial + 2 retries), then it falls back to SEE_IMAGE_FALLBACK_MODEL; stderr captured in error messages, temp files cleaned up
• Linux-only (screenshot search dirs)

Known limitations

The tool part title (set via context.metadata) is not rendered in the main TUI timeline for plugin tools — upstream opencode issue #18585. The tool row still shows ⚙ vision [filePath=...] while running and ✓ on completion.

Credits

This plugin is derived from alfaoz/opencode-see-image (MIT) by @alfaoz — the original project that gives non-vision opencode models the ability to see images. This project keeps the same image-resolution ladder and vision-routing concept while simplifying it to a single-file, Linux-only, free-model plugin. Thanks for the inspiration and the solid base.

License

MIT. Derived from alfaoz/opencode-see-image (MIT).