opencode-better-eyesight

Image understanding for opencode. Agents get an eyesight tool that asks a vision model about an image: the clipboard, something pasted into the conversation, a file path, or a URL. The vision call is routed through opencode itself (session.prompt), so it uses whatever providers and models opencode already has configured. Nothing here talks to a vendor API directly.

Most useful with text-only coding models, which otherwise can't see the screenshots you paste.

Setup

From npm:

// opencode.json / opencode.jsonc in the project root
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    ["opencode-better-eyesight", { "model": "openrouter/dots-studio/dots-3-note-preview:free" }]
  ]
}

Or from a local checkout (for development):

{ "plugin": [["./opencode-better-eyesight/index.ts", { "model": "..." }]] }

For the local path variant, run bun install in opencode-better-eyesight/ first, then restart opencode. The npm variant handles that itself.

model is optional, in opencode's provider/model-id format. Without it, the vision call uses opencode's default model.

Requires opencode 1.18 or newer (built and tested against 1.18.18; the entry point is TypeScript, which opencode loads via Bun).

Usage

Paste or attach an image. The plugin saves it to a stable path and appends a short note to your message telling the agent to call eyesight. Nothing is sent to a model at that point, so pasting is instant. Set autoAnalyze: false to skip the note entirely.

Tool arguments:

• source (required): attached (most recent image in the conversation), clipboard, a file path, an attached image's filename, an https URL, or a data: URL.
• question: what to ask. If omitted, your recent messages are forwarded as context.
• model: per-call override, provider/model-id.
• detail: brief, normal (default), or exhaustive.
• fresh: re-ask, skipping the cache.

Typical flow: paste a screenshot and ask "what error is this?" — the agent calls eyesight with the image and your question, then relays the answer. You can also name a model in chat ("use gemini for this one") and the agent passes it as model.

How it works

1. Resolves and hashes the image, writes it to <cacheDir>/images/<hash>.<ext>.
2. Builds the prompt from the question argument or your recent messages (plugin-injected blocks are stripped from the context).
3. Creates a child session linked to the current one (parentID).
4. Sends it via session.prompt with the configured model and a registered tool-less agent, so the vision call cannot run tools itself.

Calls are stateless by default: one session, one image, one question. With history: true, one session per image is reused so follow-up questions share the vision model's context; the image is only uploaded with the first question.

Answers are cached in <cacheDir>/responses/, keyed by model, question, detail level, and image hash. Identical asks return from cache with no model call, and concurrent identical calls are deduped.

Options

| Option | Default | Description | | --- | --- | --- | | model | opencode default | Vision model, provider/model-id. | | history | false | Reuse one session per image for multi-turn Q&A. | | autoAnalyze | true | Inject image pointers into messages containing images. | | timeoutMs | 120000 | Per-call limit; the child session is aborted after it. | | fetchTimeoutMs | 30000 | Timeout for downloading URL images. | | maxHistoryMessages | 4 | How many user turns to forward as context. | | contextChars | 4000 | Cap on forwarded context. | | cacheTtlHours | 168 | Cache lifetime; 0 disables caching. | | maxImageBytes | 10485760 | Image size limit (10 MB). | | cacheDir | ~/.cache/opencode-better-eyesight | Where images and cached answers live. | | agent | eyesight | Name of the registered vision agent. | | enabled | true | Set false to disable the plugin. |

Environment overrides: EYESIGHT_MODEL, EYESIGHT_HISTORY=1, EYESIGHT_AUTO_ANALYZE=0, EYESIGHT_CACHE_TTL_HOURS, EYESIGHT_CACHE_DIR, EYESIGHT_DISABLE=1.

Development

cd opencode-better-eyesight
bun install
bun run typecheck
bun test

Notes

• Images are sent as-is; there is no resizing. Very large screenshots can exceed a provider's input limit.
• Clipboard capture supports macOS (osascript) and Linux (wl-paste / xclip).
• Text read out of images is treated as untrusted data in every prompt. Instructions inside a screenshot are reported as content, never followed.

The paste-pointer and guarded-block patterns come from opencode-senses; the tool-call shape is similar to openrouter-image-mcp.