From 4fcd6e6640c3621ee60e6f09aba3ec5acdb527ef Mon Sep 17 00:00:00 2001
From: Aiden Cline <aidenpcline@gmail.com>
Date: Wed, 13 May 2026 11:44:33 -0500
Subject: [PATCH] docs: document image attachment resizing

---
 packages/web/src/content/docs/config.mdx | 29 ++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/packages/web/src/content/docs/config.mdx b/packages/web/src/content/docs/config.mdx
index ec96069c70..113544fc36 100644
--- a/packages/web/src/content/docs/config.mdx
+++ b/packages/web/src/content/docs/config.mdx
@@ -385,6 +385,35 @@ You can also configure [local models](/docs/models#local). [Learn more](/docs/mo
 
 ---
 
+### Image attachments
+
+OpenCode normalizes image attachments before sending them to the model. By default, images are resized when they exceed `2000x2000` pixels or `4718592` base64 bytes.
+
+Configure image attachment limits with the `attachment.image` option:
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "attachment": {
+    "image": {
+      "auto_resize": true,
+      "max_width": 2000,
+      "max_height": 2000,
+      "max_base64_bytes": 4718592
+    }
+  }
+}
+```
+
+- `auto_resize` - Resize images that exceed the configured limits before provider requests. Set to `false` to reject oversized images instead.
+- `max_width` - Maximum image width in pixels before resizing or rejection.
+- `max_height` - Maximum image height in pixels before resizing or rejection.
+- `max_base64_bytes` - Maximum encoded image payload size. This is the base64 payload size, not the original file size.
+
+If an image still cannot fit after resizing, OpenCode omits oversized tool-result images or fails oversized user-provided images with an image size error.
+
+---
+
 #### Provider-Specific Options
 
 Some providers support additional configuration options beyond the generic `timeout` and `apiKey` settings.