JSPM

@forceuser/opencode-img

0.1.0
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 99
  • Score
    100M100P100Q96882F
  • License MIT

OpenCode plugin that routes images from text-only models to an @img vision subagent.

Package Exports

  • @forceuser/opencode-img
  • @forceuser/opencode-img/server
  • @forceuser/opencode-img/tui

Readme

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/img-images, replaced with an absolute [Image saved to: ...] path, then analyzed by @img

Install

After publishing:

npx @forceuser/opencode-img

The installer asks where to install the plugin:

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

Non-interactive installs:

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

For local development:

npm link
opencode-img --local --yes
opencode-img --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 --local --yes --package /absolute/path/to/opencode-img
opencode-img --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 .opencode/agents/img.md automatically if it does not exist.

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/img-images.
  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 local setting is stored in .opencode/img.json. If OPENCODE_IMG_AUTO_INVOKE is set, the environment variable takes precedence over the local 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
opencode-img install --local --force --yes

Configuration

The plugin works without environment variables.

Variable Default Meaning
OPENCODE_IMG_AGENT img Subagent name used for auto-invocation
OPENCODE_IMG_MODEL empty Optional model used when auto-creating .opencode/agents/img.md; otherwise choose with /models-img
OPENCODE_IMG_CONFIG_PATH .opencode/img.json Local plugin settings file
OPENCODE_IMG_AGENT_PATH .opencode/agents/img.md Agent file path
OPENCODE_IMG_TEMP_DIR .opencode/img-images Directory for copied/saved images
OPENCODE_IMG_MAX_AGE_MS 3600000 Cleanup age for saved images
OPENCODE_IMG_AUTO_INVOKE unset Optional override for auto invoke; use .opencode/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