Attachments

Attachments add local context to a prompt as text or image media. Regardless of how a prompt is submitted, current V2 sessions make these attachment types visible to the model:

Input	Model receives
UTF-8 text file	The filename and decoded text
Directory	A non-recursive listing of its immediate files and directories
PNG, JPEG, GIF, or WebP	Image media

SVG files are treated as text, not image media. PDF, AVIF, BMP, audio, video, and other binary prompt attachments are not currently included in the model request. A client accepting a file does not mean its contents are visible to the model.

Add attachments

Desktop and web clients provide Attach file, paste, and drag-and-drop controls for supported text and image files. The desktop file picker limits one selection to 20 MiB in total; the server also applies the per-attachment limit below.

Attachment controls and client-side limits depend on the interface. For programmatic submission, see the generated API reference.

V2 prompt and command inputs represent each attachment with a uri and optional name and description. Use an absolute file: URL for a file or directory available to the server, or an inline data: URL. For a text file: URL, optional positive start and end query parameters select one-based lines:

file:///home/me/project/src/server.ts?start=20&end=60

HTTP and HTTPS attachment URLs are not supported. OpenCode materializes each attachment before admitting the prompt and rejects invalid URLs, unreadable paths, non-files other than directories, and attachments over 20 MiB decoded. The server infers the media type from the bytes. A supplied filename or data URL media type does not make an unsupported binary format model-visible.

Configure image processing

Configure image normalization in opencode.json or opencode.jsonc:

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "media": {
    "image": {
      "auto_resize": true,
      "max_width": 2000,
      "max_height": 2000,
      "max_base64_bytes": 5242880,
    },
  },
}

All fields are optional:

Field	Default	Behavior
`auto_resize`	`true`	Resize an image that exceeds any configured limit. If `false`, reject it.
`max_width`	`2000`	Maximum width in pixels. Must be a positive integer.
`max_height`	`2000`	Maximum height in pixels. Must be a positive integer.
`max_base64_bytes`	`5242880`	Maximum byte length of the Base64-encoded image string. Must be a positive integer.

The read tool recognizes PNG, JPEG, GIF, and WebP by their contents and will ingest at most 20 MiB of source image bytes. It decodes the image and compares its width, height, and encoded Base64 length with all three configured limits.

When auto_resize is true, OpenCode preserves the aspect ratio, scales the image down to the dimension limits, and tries progressively smaller PNG and JPEG encodings until the Base64 limit is met. The resulting media type can therefore change to PNG or JPEG. If no encoding fits, the tool call fails.

When auto_resize is false, exceeding any limit fails the tool call without modifying the image. An image that cannot be decoded also fails. If the image resizer cannot be loaded, OpenCode uses the original image instead, so these settings are processing limits rather than an upload or security boundary.

Limits and provider behavior

Direct prompt attachments are limited to 20 MiB decoded per item by the V2 server. Client-specific limits can be lower.
max_base64_bytes counts the encoded Base64 characters in bytes, not the decoded file size and not the complete data: URL.
Text attachments are inserted into the prompt as text and do not require a multimodal model. Large text read through the read tool has separate paging and truncation limits.
Image attachments use provider-native image input. Provider errors can still occur when OpenCode’s limits pass but the selected model’s limits do not.
PDFs and other unsupported binary prompt attachments should be converted to text or supported images before attaching them.