Opencode Image Compressor plugin

opencode-image-compressor shrinks large image attachments into smaller JPEG payloads before they are passed into the model.

Why this plugin exists

Sending image attachments in OpenCode could sometimes trigger session compaction before the model had a chance to retain the actual visual context. When that happened, the conversation summary might only keep a reference to the uploaded image name, which made it difficult to continue the session from where it left off.

Re-sending the same image after compaction could trigger compaction again, so the issue would repeat instead of resolving itself.

This plugin works around that by aggressively compressing images before they are sent to the model. It reduces image size by downscaling and lowering visual quality while still preserving enough detail for the AI to efficiently and successfully process image.

Because the model receives a much smaller image, it may also process the attachment faster than a full-size original with far more pixels than it actually needs saving tokens.

It is especially useful for screenshot-heavy workflows and tools that send images into the session.

What it does

• checks supported images larger than 200 KB
• rewrites successful outputs as image/jpeg
• aims for roughly 50 KB
• accepts results up to 200 KB
• supports image/jpeg, image/jpg, image/pjpeg, image/png, and image/webp
• keeps the original file when recompression fails or would not reduce size

Installation

Requirements:

• OpenCode plugin support with @opencode-ai/plugin >= 1.2.27
• a working sharp install in the runtime environment

This plugin is intended to work on macOS, Linux and Windows as long as sharp installs and loads correctly on that machine.

In OpenCode setup, adding it to opencode.json is enough:

{
  "plugin": ["opencode-image-compressor"]
}

If your environment does not auto-resolve npm plugins, install it first:

bun add opencode-image-compressor

If installing from source:

bun install
bun run build

Development

bun install
bun run typecheck
bun run build

Debug logging

Enable verbose logging:

OPENCODE_IMAGE_COMPRESSOR_DEBUG=true

Optional custom log file path:

OPENCODE_IMAGE_COMPRESSOR_DEBUG_LOG_PATH=/tmp/opencode-image-compressor.log

When enabled, the plugin:

• appends trace lines to the log file for each inspected attachment
• emits runtime status lines to stderr

When debug is disabled, routine status messages stay silent and only actual errors are written to stderr.

On macOS, /tmp maps to /private/tmp, so check both locations if needed.