opencode-see-image 0.9.1 → 0.9.3

package/.claude/settings.local.json

@@ -6,7 +6,13 @@
       "Bash(FILTER_BRANCH_SQUELCH_WARNING=1 git filter-branch -f --msg-filter 'sed \"/Co-Authored-By: Claude/d\" | sed -e :a -e \"/^\\\\n*$/{\\\\$d;N;ba\" -e \"}\"' HEAD~2..HEAD)",
       "Bash(echo \"--- created, exit $? ---\")",
       "Bash(node -p \"require\\('./package.json'\\).version\")",
-      "Bash(echo \"local package.json version: $\\(node -p \"require\\('./package.json'\\).version\" \\)\")"
+      "Bash(echo \"local package.json version: $\\(node -p \"require\\('./package.json'\\).version\" \\)\")",
+      "Bash(bun --version)",
+      "Bash(bun pm *)",
+      "Read(//Users/alfa/Documents/opencodeprojects/opencode-see-image/bun-types/**)",
+      "Bash(bun run *)",
+      "WebFetch(domain:docs.z.ai)",
+      "Bash(npm publish *)"
     ]
   }
 }

package/README.md

@@ -1,18 +1,18 @@
 # opencode-see-image
 
-Give non-vision opencode models the ability to **see images and screenshots** by routing them to a vision-capable model.
+give non-vision opencode models the ability to see images and screenshots by routing them to a vision-capable model.
 
-When a user attaches a screenshot to a text-only model, opencode rejects it with an error. This plugin intercepts that flow by registering a `see_image` tool that sends the image to a vision model and returns a textual description the primary model can reason about.
+when a user attaches a screenshot to a text-only model, opencode rejects it with an error. This plugin intercepts that flow by registering a `see_image` tool that sends the image to a vision model and returns a textual description the primary model can reason about.
 
-## Install
+## install
 
-**Option A, one command (recommended):**
+**one command (recommended):**
 ```bash
 opencode plugin opencode-see-image --global
 ```
 This installs the package and adds it to your config. Then restart opencode.
 
-**Option B, edit config manually:**
+**edit config manually:**
 
 Add the plugin to your opencode config:
 
@@ -25,76 +25,76 @@ Add the plugin to your opencode config:
 ```
 Then restart opencode.
 
-## Install via your agent
+## install via your agent (for some reason?)
 
-Ask your agent:
+ask your agent:
 ```
 install the opencode-see-image plugin
 ```
-It'll run `opencode plugin opencode-see-image --global` and tell you to restart.
+it'll run `opencode plugin opencode-see-image --global` and tell you to restart. 
 
-## Prerequisites
+## prerequisites
 
-You need a connected vision-capable provider. The plugin auto-detects whichever you have connected, **either of these works**:
+you need a connected vision-capable provider. The plugin auto-detects whichever you have connected, **either of these work**:
 
-### Free (OpenCode Zen)
-1. Run `/connect` in opencode
-2. Select **opencode** (OpenCode Zen)
-3. Paste your API key from [opencode.ai/auth](https://opencode.ai/auth)
+### free (OpenCode Zen)
+1. run `/connect` in opencode
+2. select **opencode** (OpenCode Zen)
+3. paste your API key from [opencode.ai/auth](https://opencode.ai/auth)
 
-The plugin falls back to **mimo-v2.5-free**. No subscription needed.
+the plugin falls back to **mimo-v2.5-free**.
 
-### Paid, w/ OpenCode Go
-1. Run `/connect` in opencode
-2. Select **opencode-go**
-3. Paste your API key from [opencode.ai/auth](https://opencode.ai/auth)
+### paid, w/ OpenCode Go
+1. run `/connect` in opencode
+2. select **opencode-go**
+3. paste your API key from [opencode.ai/auth](https://opencode.ai/auth)
 
-The plugin prefers **minimax-m3** via opencode-go (~3000ms) when available.
+the plugin prefers **minimax-m3** via opencode-go when available.
 
-### Paid, w/ another provider
+### paid, w/ another provider
 
-Set the `SEE_IMAGE_*` env vars to point at any Anthropic-Messages-compatible endpoint. See [Configuration](#configuration) below.
+set the `SEE_IMAGE_*` env vars to point at any Anthropic-Messages-compatible endpoint. see [Configuration](#configuration) below.
 
-**Resolution order:** explicit `SEE_IMAGE_API_KEY` env → configured `SEE_IMAGE_PROVIDER` → `opencode-go` (MiniMax M3) → `opencode` (mimo-v2.5-free, free).
+**the resolve order:** explicit `SEE_IMAGE_API_KEY` env → configured `SEE_IMAGE_PROVIDER` → `opencode-go` (MiniMax M3) → `opencode` (mimo-v2.5-free).
 
-## How it works
+## how the _eye surgery_ works
 
 ```
 user attaches screenshot
-        │
-        ▼
+        |
+        v
 opencode rejects it: 'this model does not support image input'
-        │  (the model only sees the filename, no pixels)
-        ▼
+        |      (the model only sees the filename)
+        v
 plugin's system-prompt instructions tell the model to call see_image
-        │
-        ▼
+        |
+        v
 see_image tool:
-  1. queries opencode's SQLite DB for the image (handles clipboard pastes, dragged files, screenshots)
+  1. queries opencode's SQLite DB for the image
   2. falls back to filesystem search if not in DB
   3. sends the image to the vision model via opencode's SDK
   4. returns the textual description
-        │
-        ▼
+        |
+        v
 primary model answers using the description
 ```
 
-## The `see_image` tool
+## the `see_image` tool
 
-The plugin registers a `see_image` tool with two arguments:
+the plugin registers a `see_image` tool with two arguments:
 
-| Arg | Type | Required | Description |
+| arg | type | required? | description |
 |---|---|---|---|
-| `filePath` | string | yes | Path to the image. Absolute path, or a bare filename like `"Screenshot 2026-06-18 at 17.32.24.png"` to auto-locate. |
-| `question` | string | no | A specific question about the image. Defaults to a general detailed description. Use this to focus on a particular detail (e.g. `"What error is shown in the terminal?"`). |
+| `filePath` | string | y | path to the image. Absolute path, or a bare filename like `"Screenshot 2026-06-18 at 17.32.24.png"` to auto-locate. |
+| `question` | string | n | a specific question about the image. Defaults to a general detailed description. Use this to focus on a particular detail (e.g. `"What error is shown in the terminal?"`). |
 
-Your model calls this tool automatically when you attach a screenshot, you don't need to do anything special. The `question` arg is optional; the model uses it when you ask something specific about the image.
+your model calls this tool automatically when you attach a screenshot, you don't need to do anything special. The `question` arg is optional; the model uses it when you ask something specific about the image.
 
-## Configuration
+## configuration
 
-All settings are env-var overrides. The plugin uses opencode's SDK client by default (handles auth automatically). Set `SEE_IMAGE_API_KEY` to bypass the SDK and call an HTTP endpoint directly.
+all settings are env-var overrides. The plugin uses opencode's SDK client by default (handles auth automatically). Set `SEE_IMAGE_API_KEY` to bypass the SDK and call an HTTP endpoint directly.
 
-| Env var | Default | Description |
+| env var | default | description |
 |---|---|---|
 | `SEE_IMAGE_MODEL` | `minimax-m3` | Vision model ID |
 | `SEE_IMAGE_PROVIDER` | `opencode-go` | Provider ID for SDK routing |
@@ -104,9 +104,9 @@ All settings are env-var overrides. The plugin uses opencode's SDK client by def
 | `SEE_IMAGE_USER_AGENT` | _(Chrome UA)_ | User-Agent header (HTTP mode only) |
 | `SEE_IMAGE_TIMEOUT` | `30000` | Per-candidate timeout in ms. Prevents hanging on slow models. |
 
-### Using a different vision model
+### using a different vision model
 
-Any Anthropic-Messages-compatible endpoint works. For example, to use a direct MiniMax key:
+any Anthropic-Messages-compatible endpoint works. for example, to use a direct MiniMax key:
 
 ```bash
 export SEE_IMAGE_ENDPOINT="https://api.minimax.io/v1/messages"
@@ -114,60 +114,61 @@ export SEE_IMAGE_MODEL="minimax-m3"
 export SEE_IMAGE_API_KEY="your-minimax-key"
 ```
 
-To use a different opencode-go model (e.g. Kimi K2.7):
+to use a different opencode-go model (e.g. Kimi K2.7):
 
 ```bash
 export SEE_IMAGE_MODEL="kimi-k2.7-code"
 ```
 
-### Verified vision-capable models
+### verified vision-capable models
 
 **Free (OpenCode Zen):**
 
-| Model | Speed | Notes |
-|---|---|---|
-| `mimo-v2.5-free` | — | Free. Default fallback when only Zen is connected (routed via CLI). |
-| `big-pickle` | ~12000ms | Free. Accurate. Alternative Zen fallback. |
+| model | Notes |
+|---|---|
+| `mimo-v2.5-free` |  free. may be a bit slow. default fallback when only Zen is connected (routed via CLI). |
+| `big-pickle` | for some reason, big pickle works as an image capable model when called through the sdk w/ an active opencode go sub. |
 
-**Paid (OpenCode Go):**
+**paid (OpenCode Go):**
 
-| Model | Speed | Notes |
+| model | speed | notes |
 |---|---|---|
-| `minimax-m3` | ~3000ms | Default. Fast, clean text output. |
-| `kimi-k2.7-code` | ~7000ms | Clean output, accurate. |
-| `kimi-k2.6` | ~20000ms | Accurate but slow. |
-| `qwen3.7-plus` | ~20000ms | Emits thinking blocks (handled). |
+| `minimax-m3` | ~3000ms | default. fast, clean, and accurate. |
+| `kimi-k2.7-code` | ~7000ms | clean and accurate. |
+| `kimi-k2.6` | ~12000ms | accurate but slow. |
+| `qwen3.7-plus` | ~15000ms | slow, spends a bit more tokens because of thinking. |
 
-## Updating
+## updating
 
-**Auto-update (built in):** the plugin checks npm for a newer version on every opencode startup. If one exists, it updates itself via `opencode plugin --force` (uses opencode's bundled bun, no global bun needed) and shows a toast: *"opencode-see-image updated to X.Y.Z, restart opencode to apply"*. You just need to restart opencode to load the new version. Nothing to configure.
+**auto-update (built in):** uses the opencode-plugin-update-kit and shows a toast: *"opencode-see-image updated to X.Y.Z, restart opencode to apply"*. You just need to restart opencode to load the new version.
 
-**Manual update** (if you want to force it now):
+**manual update**:
 ```bash
 opencode plugin opencode-see-image --force --global
 ```
-Then restart opencode. (No bun required, this uses opencode's own bun.)
+then restart opencode.
 
-**Pin a version** in your config to opt out of auto-updates:
+**pin a version** in your config to opt out of auto-updates:
 ```jsonc
 "plugin": ["opencode-see-image@0.4.2"]
 ```
 
-## Limitations
+## kimitations
 
-- **macOS-only filesystem search** — the filesystem fallback targets macOS screenshot temp dirs. Linux/Windows users should rely on the DB lookup (which is cross-platform) or pass absolute paths.
+- **macOS-only filesystem search**. the filesystem fallback targets macOS screenshot temp dirs. Linux/Windows users should rely on the DB lookup (which is cross-platform) or pass absolute paths.
+> if you can add compat for more platforms, i would love a pr.
 
-## File search locations
+## file search locations
 
-When opencode rejects an image attachment, the model only receives a bare filename. `see_image` searches these locations in order:
+when opencode rejects an image attachment, the model only receives a bare filename. `see_image` searches these locations in order:
 
 1. `$TMPDIR/TemporaryItems/NSIRD_screencaptureui_*/` (where macOS stashes dragged screenshots)
 2. `$TMPDIR/TemporaryItems/`
 3. `~/Desktop` (default screenshot save location)
 4. `~/Downloads`
-5. Current working directory
+5. current working directory
 
-Pass an absolute `filePath` to skip the search.
+pass an absolute `filePath` to skip the search.
 
 ## License
 

package/index.ts

@@ -218,7 +218,6 @@ function readProviderKey(providerID: string): string | null {
 
 async function seeImageViaSDK(
   client: any,
-  $: any,
   dataUrl: string,
   mediaType: string,
   prompt: string,
@@ -226,28 +225,54 @@ async function seeImageViaSDK(
 ): Promise<{ text: string; model: string; provider: string }> {
   const errors: string[] = []
 
-  // Write image to a temp file so the server can read it directly. Use the
-  // real extension so the CLI can sniff the type correctly.
   const b64 = dataUrl.split(",")[1] || ""
   const ext =
     Object.entries(EXT_MEDIA).find(([, m]) => m === mediaType)?.[0] || "png"
-  const tmpPath = path.join(os.tmpdir(), `see-image-${Date.now()}.${ext}`)
-  try {
-    fs.writeFileSync(tmpPath, Buffer.from(b64, "base64"))
-  } catch {}
+
+  // The free CLI fallback needs the image on disk. Write it lazily and only
+  // once, so the common SDK/dataURL path never touches the filesystem. Use the
+  // real extension so the CLI can sniff the type correctly.
+  let tmpPath: string | null = null
+  const ensureTmpFile = (): string | null => {
+    if (tmpPath) return tmpPath
+    const p = path.join(os.tmpdir(), `see-image-${Date.now()}.${ext}`)
+    try {
+      fs.writeFileSync(p, Buffer.from(b64, "base64"))
+      tmpPath = p
+    } catch {
+      return null
+    }
+    return tmpPath
+  }
 
   // For free opencode models, use CLI instead of SDK (SDK returns empty).
-  // Bun's $ doesn't accept an AbortSignal, so race the output against a
-  // timeout to actually bound how long a slow model can hang us.
+  // Use Bun.spawn (not $) so we get a killable handle: Bun's $ ShellPromise
+  // has no .kill(), so racing it against a timeout would leak the process.
+  // We kill the child on both timeout and external abort.
   const freeFallback = async (modelID: string, userPrompt: string): Promise<string | null> => {
+    const filePath = ensureTmpFile()
+    if (!filePath) return null
+    const proc = Bun.spawn(
+      [
+        "opencode",
+        "run",
+        "-f",
+        filePath,
+        "-m",
+        `opencode/${modelID}`,
+        userPrompt,
+        "--format",
+        "json",
+        "--dangerously-skip-permissions",
+      ],
+      { stdout: "pipe", stderr: "ignore" },
+    )
+    const timer = setTimeout(() => proc.kill(), TIMEOUT)
+    const onAbort = () => proc.kill()
+    abort?.addEventListener("abort", onAbort)
     try {
-      const proc = $`opencode run -f ${tmpPath} -m opencode/${modelID} ${userPrompt} --format json --dangerously-skip-permissions`.nothrow()
-      const out = await Promise.race([
-        proc.text(),
-        new Promise<never>((_, reject) =>
-          setTimeout(() => reject(new Error(`timed out after ${TIMEOUT}ms`)), TIMEOUT),
-        ),
-      ])
+      const out = await new Response(proc.stdout).text()
+      await proc.exited
       for (const line of out.split("\n").filter(Boolean)) {
         try {
           const parsed = JSON.parse(line)
@@ -256,7 +281,10 @@ async function seeImageViaSDK(
           }
         } catch {}
       }
-    } catch {}
+    } catch {} finally {
+      clearTimeout(timer)
+      abort?.removeEventListener("abort", onAbort)
+    }
     return null
   }
 
@@ -286,7 +314,15 @@ async function seeImageViaSDK(
 
       let sessionID: string | undefined
       try {
-        const sessionRes = await client.session.create({ body: {} })
+        const sessionRes = await Promise.race([
+          client.session.create({ body: {} }),
+          new Promise<never>((_, reject) =>
+            setTimeout(
+              () => reject(new Error(`session.create timed out after ${TIMEOUT}ms`)),
+              TIMEOUT,
+            ),
+          ),
+        ])
         sessionID = sessionRes.data?.id
         if (!sessionID) {
           errors.push(`${providerID}/${modelID}: no session ID`)
@@ -344,7 +380,10 @@ async function seeImageViaSDK(
 
     if (!result) {
       const apiKey =
-        process.env.SEE_IMAGE_API_KEY || readProviderKey("opencode-go")
+        process.env.SEE_IMAGE_API_KEY ||
+        (process.env.SEE_IMAGE_PROVIDER &&
+          readProviderKey(process.env.SEE_IMAGE_PROVIDER)) ||
+        readProviderKey("opencode-go")
       if (apiKey) {
         try {
           result = await seeImageViaHTTP(b64, mediaType, prompt, abort, apiKey)
@@ -364,7 +403,9 @@ async function seeImageViaSDK(
       `see_image: SDK vision call failed for all candidates. ${errMsg}.${hint}`,
     )
   } finally {
-    try { fs.unlinkSync(tmpPath) } catch {}
+    if (tmpPath) {
+      try { fs.unlinkSync(tmpPath) } catch {}
+    }
   }
 }
 
@@ -481,7 +522,17 @@ const SeeImagePlugin: Plugin = async (ctx) => {
         .string()
         .optional()
         .describe(
-          "Optional specific question about the image. Defaults to a general detailed description.",
+          [
+            "What to ask the vision model. Omit for a general detailed description.",
+            "Tailor it to the situation for much better results:",
+            '- Reading/transcribing text or code: "Transcribe all text exactly, preserving layout, line breaks, and code indentation."',
+            '- An error or stack trace screenshot: "Quote the exact error message and stack trace, then state the likely cause."',
+            '- Reproducing a UI as code: "Describe the layout, components, text, colors, and spacing precisely enough to rebuild this UI in code."',
+            '- A technical diagram/architecture: "Explain this diagram: list each component and the relationships and data/flow direction between them."',
+            '- A chart/graph/dashboard: "Read this visualization: axes, series, key values, and the main takeaway."',
+            '- Comparing against an expected design: "Describe this UI in detail so it can be diffed against an expected layout (note any visible defects or misalignment)."',
+            "Otherwise pass the user's own specific question verbatim.",
+          ].join("\n"),
         ),
     },
     async execute(args, context) {
@@ -500,7 +551,6 @@ const SeeImagePlugin: Plugin = async (ctx) => {
       } else {
         result = await seeImageViaSDK(
           client,
-          $,
           resolved.dataUrl,
           resolved.mediaType,
           prompt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-see-image",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Give non-vision opencode models the ability to see images/screenshots by routing them to a vision-capable model (MiniMax M3 via opencode-go by default).",
   "type": "module",
   "main": "index.ts",
@@ -23,6 +23,6 @@
   "license": "MIT",
   "dependencies": {
     "@opencode-ai/plugin": "^1.15.0",
-    "opencode-plugin-update-kit": "^0.1.0"
+    "opencode-plugin-update-kit": "^0.2.0"
   }
 }