opencode-img

OpenCode plugin that lets a text-only main model work with images through a small multimodal subagent named @img.

It was built for setups like:

• main model: lumi/DeepSeek-V4-Flash, text-only
• image model: selected explicitly with /models-img
• behavior: pasted or attached images are saved to .opencode/opencode-img-files, replaced with an absolute [Image saved to: ...] path, then analyzed by @img

Install

After publishing:

npx @forceuser/opencode-img install

The installer asks where to install the plugin:

• local: current OpenCode project
• global: all OpenCode projects

Install commands replace an existing plugin entry automatically. Registry installs are pinned to the current package version to avoid stale OpenCode package cache.

Non-interactive installs:

npx @forceuser/opencode-img install --local --yes
npx @forceuser/opencode-img install --global --yes

For local development:

npm link
opencode-img install --local --yes
opencode-img install --global --yes

When opencode-img is available through npm link, the installer automatically passes the linked package directory to OpenCode instead of resolving @forceuser/opencode-img from the npm registry. You can still pass an explicit package path when needed:

opencode-img install --local --yes --package /absolute/path/to/opencode-img
opencode-img install --global --yes --package /absolute/path/to/opencode-img

OpenCode detects both package entrypoints:

• ./server for message rewriting and auto-invoking @img
• ./tui for the /models-img picker

The server plugin creates the install-scope agents/img.md automatically if it does not exist.

Agent and model settings follow the installation scope:

• local install: <project>/.opencode/agents/img.md and <project>/.opencode/img.json
• global install: <opencode config>/agents/img.md and <opencode config>/img.json, usually ~/.config/opencode/...

Saved pasted images stay project-local in <project>/.opencode/opencode-img-files.

Manual fallback:

opencode plugin @forceuser/opencode-img
opencode plugin @forceuser/opencode-img --global
opencode plugin /absolute/path/to/opencode-img

Usage

Start OpenCode, choose a vision model, and then paste or attach an image while using a text-only model:

/models-img

Read this error screenshot and tell me what failed.

Expected flow:

1. The plugin detects the image attachment.
2. If the active model does not support image input, the image is saved to .opencode/opencode-img-files.
3. The raw image part is replaced with [Image saved to: <absolute path>].
4. The plugin adds @img automatically by default.
5. @img reads the saved file using its vision model and returns structured findings.
6. The main model uses those findings to answer.

Choose The @img Model

Inside OpenCode:

/models-img

This opens a picker filtered to models whose OpenCode metadata reports image input support. Provider names are shown as groups, and item titles show only model names.

From a terminal:

opencode-img model lumi/Kimi-K2.6

Print the current model:

opencode-img model

Toggle Auto Invoke

By default, the plugin adds @img automatically after saving images for a text-only model.

Inside OpenCode:

/img-auto

This toggles auto invoke on or off. You can also use explicit modes:

/img-auto on
/img-auto off
/img-auto status

From a terminal:

opencode-img auto
opencode-img auto on
opencode-img auto off
opencode-img auto toggle

The auto-invoke setting follows the install scope: local installs use <project>/.opencode/img.json, while global installs use <opencode config>/img.json. If OPENCODE_IMG_AUTO_INVOKE is set, the environment variable takes precedence over the file.

Create the agent file manually:

opencode-img init

Install or reinstall the plugin from a terminal:

opencode-img install
opencode-img install --local --yes
opencode-img install --global --yes

Uninstall the plugin from OpenCode config:

opencode-img uninstall
opencode-img uninstall --local --yes
opencode-img uninstall --global --yes
npx @forceuser/opencode-img uninstall --global --yes

Uninstall removes plugin entries from both opencode.json and tui.json. It also removes the install-scope agents/img.md, img.json, and img.log files if they exist, plus project-local saved files in <project>/.opencode/opencode-img-files. It also removes the legacy <project>/.opencode/img-images directory when present.

Configuration

The plugin works without environment variables.

| Variable | Default | Meaning | | --- | --- | --- | | OPENCODE_IMG_AGENT | img | Subagent name used for auto-invocation | | OPENCODE_IMG_SCOPE | detected | Optional override: local or global | | OPENCODE_IMG_MODEL | empty | Optional model used when auto-creating the install-scope agents/img.md; otherwise choose with /models-img | | OPENCODE_IMG_CONFIG_PATH | install-scope img.json | Plugin settings file | | OPENCODE_IMG_AGENT_PATH | install-scope agents/img.md | Agent file path | | OPENCODE_IMG_TEMP_DIR | .opencode/opencode-img-files | Project-local directory for copied/saved images | | OPENCODE_IMG_MAX_AGE_MS | 3600000 | Cleanup age for saved images | | OPENCODE_IMG_MAX_FILES | 50 | Maximum saved image files kept in the temp directory | | OPENCODE_IMG_AUTO_INVOKE | unset | Optional override for auto invoke; use the install-scope img.json or /img-auto by default | | OPENCODE_IMG_DEBUG | false | Set to true to write diagnostic logs | | OPENCODE_IMG_LOG_FILE | .opencode/img.log | Path for JSONL debug logs | | OPENCODE_IMG_DISABLED | false | Set to true to disable all plugin hooks | | OPENCODE_IMG_FORCE_TEXT_ONLY | false | Set to true to always route images through @img | | OPENCODE_IMG_TEXT_ONLY_MODELS | empty | Comma-separated model ids treated as text-only when metadata is unavailable |

By default, OPENCODE_IMG_TEXT_ONLY_MODELS is empty. The plugin relies on OpenCode model metadata first and caches image capabilities by modelId and provider/model.

Debugging

Enable logs:

OPENCODE_IMG_DEBUG=true opencode

Logs are JSON lines:

.opencode/img.log

Useful log fields:

• decision.support: whether the model supports image input
• decision.supportSource: model or cache
• cache.key: the cached model id used by an early hook
• savedPaths: files written for @img

Publish

Before publishing:

npm run check
npm run pack:dry

Then:

npm publish

The package is ESM-only and targets Node.js 20+.

Local Development

Run syntax checks:

npm run check

Smoke-test loading from a project:

npm link
opencode-img install --local --yes
opencode-img install --global --yes
OPENCODE_IMG_DEBUG=true opencode

License

MIT