Skip to content

OpenCode Vision Setup Plan

Status: PLANNED — not yet installed (saved 2026-08-15 for future install)

What it adds

opencode-vision PyPI package (pure Python, stdlib MCP server) exposes 3 tools to ANY model — including text-only big-pickle: - vision_describe(path, prompt?) — scene description - vision_ocr(path) — extract all text (local PaddleOCR, SOTA) - vision_analyze(path) — metadata + description + OCR

Closes the recurring "model can't see images" gap for canva editor exports, storefront mockups, desktop screenshots.

Cost: free (Gemini free tier for describe/analyze + local PaddleOCR for text). No OpenCode Zen credits consumed.

Why chosen

  • opencode-senses plugin (Reddit, itsmeadarsh2008/opencode-senses) requires NVIDIA Ampere+ GPU or Apple Silicon — cannot run on the OptiPlex 7020 (Intel HD 4600 iGPU only, PCIe x1 slot). That's the dead end this replaces.
  • Local Ollama VLM rejected: contradicts earlier "no local Ollama" preference; slower.

Install steps

1. User step — get free Gemini API key

  • Sign in at https://aistudio.google.com (use aussiedini@gmail.com)
  • Get API key (starts AIza...), copy it

2. Install the server

uv tool install "opencode-vision[paddle]"
- Installs opencode-vision → ~/.local/bin - Fallback (PEP 668 Arch): pip install --break-system-packages "opencode-vision[paddle]" - Note: pulls paddlepaddle (~few hundred MB, one-time, CPU-friendly)

3. Config — edit ~/.config/opencode/opencode.json

  • BACKUP FIRST: cp opencode.json opencode.json.n
  • Add MCP entry (inline env key — DECIDED, matches existing firecrawl/shopify pattern; no ~/.config/opencode/.env file exists): 
    "vision": {
  "type": "local",
  "command": ["opencode-vision"],
  "environment": { "GOOGLE_API_KEY": "<key>" }
}
  • Restart OpenCode to load

4. Verify (CLI checks, no LSP)

opencode-vision describe ~/path/to/png
opencode-vision ocr ~/path/to/png
opencode mcp list        # confirm vision connected
- Session test: attach a canva export / screenshot, ask big-pickle to vision_analyze it

5. After success

  • Update Memory MCP with vision server entry + key location
  • Consider: wire into canva editor (editor-server) / desktop_mcp later

Key detection order (server auto-reads)

  1. GOOGLE_API_KEY env var
  2. GOOGLE_GENERATIVE_AI_API_KEY env var
  3. ~/.config/opencode/.env
  4. ~/.env
  5. $PWD/.env

Gotchas / notes

  • PaddleOCR text extraction stays local; only describe/analyze/handwriting image bytes go to Google (free tier)
  • Runtime: Python >= 3.10 (system has 3.14.6 — OK)
  • Requires pillow (auto-resize)
  • Use uv if possible (matches gimp/youtube-mcp workflow)