22title : " Attachments"
33---
44
5- Attachments add local context to a prompt as text or image media. Regardless
6- of how a prompt is submitted, current V2 sessions make these attachment types
7- visible to the model:
5+ ## Attach
86
9- | Input | Model receives |
10- | ----------------------- | -------------------------------------------------------------- |
11- | UTF-8 text file | The filename and decoded text |
12- | Directory | A non-recursive listing of its immediate files and directories |
13- | PNG, JPEG, GIF, or WebP | Image media |
7+ Attach a local file, then ask OpenCode to use it in your prompt. In the desktop
8+ or web client, choose ** Attach file** , paste a file, or drag it into the prompt.
149
15- SVG files are treated as text, not image media. PDF, AVIF, BMP, audio, video,
16- and other binary prompt attachments are not currently included in the model
17- request. A client accepting a file does not mean its contents are visible to
18- the model.
10+ ``` text
11+ Summarize the attached README.md and list the required setup steps.
12+ ```
13+
14+ Desktop file-picker selections can total up to 20 MiB. Other interfaces may
15+ apply lower client-side limits.
1916
2017<Callout type = " warning"
21- Use a model that supports image input before attaching an image. OpenCode passes supported image media to the selected
22- provider, but the provider and model still enforce their own formats, dimensions, file counts, and size limits . A
23- text-only model may reject the request.
18+ Choose a model with image input before attaching an image. OpenCode can pass supported images to the provider, but the
19+ provider and model still enforce their own formats, dimensions, file counts, and sizes . A text-only model may reject the
20+ request.
2421</Callout >
2522
26- ## Add attachments
23+ ## Syntax
2724
28- Desktop and web clients provide ** Attach file ** , paste, and drag-and-drop controls for supported text and image files. The
29- desktop file picker limits one selection to 20 MiB in total; the server also applies the per-attachment limit below.
25+ V2 prompt and command inputs describe an attachment with a ` uri ` and optional
26+ ` name ` and ` description ` :
3027
31- Attachment controls and client-side limits depend on the interface. For programmatic submission, see the generated
32- [ API reference] ( /api ) .
28+ ``` json
29+ {
30+ "uri" : " file:///home/me/project/src/server.ts"
31+ "name" : " server.ts"
32+ "description" : " HTTP server entrypoint"
33+ }
34+ ```
3335
34- V2 prompt and command inputs represent each attachment with a ` uri ` and
35- optional ` name ` and ` description ` . Use an absolute ` file: ` URL for a file or
36- directory available to the server, or an inline ` data: ` URL. For a text ` file: `
37- URL, optional positive ` start ` and ` end ` query parameters select one-based
38- lines:
36+ Use an absolute ` file: ` URL for a file or directory that is available to the
37+ server. For text files, positive ` start ` and ` end ` parameters select one-based
38+ lines.
3939
4040``` text
4141file:///home/me/project/src/server.ts?start=20&end=60
4242```
4343
44- HTTP and HTTPS attachment URLs are not supported. OpenCode materializes each
45- attachment before admitting the prompt and rejects invalid URLs, unreadable
46- paths, non-files other than directories, and attachments over 20 MiB decoded.
47- The server infers the media type from the bytes. A supplied filename or data
48- URL media type does not make an unsupported binary format model-visible.
44+ Use a ` data: ` URL to send content inline:
45+
46+ ``` json
47+ {
48+ "uri" : " data:text/plain;base64,SGVsbG8sIE9wZW5Db2RlIQ=="
49+ "name" : " greeting.txt"
50+ }
51+ ```
52+
53+ HTTP and HTTPS attachment URLs are not supported. See the generated
54+ [ API reference] ( /api ) for programmatic prompt submission.
55+
56+ ## Formats
57+
58+ Current V2 sessions make these attachment types visible to the model:
59+
60+ | Input | Model receives | Example |
61+ | ----------------------- | -------------------------------------------------------------- | ------------------ |
62+ | UTF-8 text file | Filename and decoded text | ` README.md ` |
63+ | Directory | Non-recursive listing of immediate files and directories | ` file:///home/me/ ` |
64+ | PNG, JPEG, GIF, or WebP | Image media | ` diagram.png ` |
65+
66+ SVG is treated as text. PDF, AVIF, BMP, audio, video, and other binary prompt
67+ attachments are not included in the model request. Convert an unsupported
68+ binary to text or a supported image first; for example, export a PDF page as
69+ ` page-1.png ` before attaching it.
4970
50- ## Configure image processing
71+ OpenCode reads each attachment before admitting the prompt. It rejects invalid
72+ URLs, unreadable paths, paths other than files or directories, and decoded
73+ attachments over 20 MiB. Media type is detected from the bytes, so changing a
74+ filename or ` data: ` URL media type does not make an unsupported binary visible.
75+
76+ ## Images
5177
5278Configure image normalization in ` opencode.json ` or ` opencode.jsonc ` :
5379
@@ -67,41 +93,70 @@ Configure image normalization in `opencode.json` or `opencode.jsonc`:
6793
6894All fields are optional:
6995
70- | Field | Default | Behavior |
71- | ------------------ | --------: | ---------- ------------------------------------------------------------------------- |
72- | ` auto_resize ` | ` true ` | Resize an image that exceeds any configured limit. If ` false ` , reject it. |
73- | ` max_width ` | ` 2000 ` | Maximum width in pixels. Must be a positive integer. |
74- | ` max_height ` | ` 2000 ` | Maximum height in pixels. Must be a positive integer. |
75- | ` max_base64_bytes ` | ` 5242880 ` | Maximum byte length of the Base64-encoded image string. Must be a positive integer. |
96+ | Field | Default | Behavior |
97+ | ------------------ | --------- | ------------------------------------------------------------------------- |
98+ | ` auto_resize ` | ` true ` | Resize an image over a configured limit; when ` false ` , reject the image. |
99+ | ` max_width ` | ` 2000 ` | Maximum width in pixels; must be a positive integer. |
100+ | ` max_height ` | ` 2000 ` | Maximum height in pixels; must be a positive integer. |
101+ | ` max_base64_bytes ` | ` 5242880 ` | Maximum bytes in the Base64-encoded image; must be a positive integer. |
76102
77- <Callout type = " note"
78- These settings apply to supported image media attached directly to prompts and images produced by the built-in ` read `
79- tool. If the image resizer is unavailable, OpenCode passes the original image through unchanged.
80- </Callout >
103+ For example, this rejects rather than resizes an image wider than 1200 pixels:
104+
105+ ``` jsonc title="opencode.jsonc"
106+ {
107+ " media" : {
108+ " image" : {
109+ " auto_resize" : false ,
110+ " max_width" : 1200 ,
111+ },
112+ },
113+ }
114+ ```
115+
116+ These settings apply both to supported images attached to prompts and to images
117+ returned by the built-in ` read ` tool.
118+
119+ ## Processing
120+
121+ The ` read ` tool recognizes PNG, JPEG, GIF, and WebP by their contents and reads
122+ up to 20 MiB of source image data. It checks width, height, and Base64 length
123+ against the configured image limits.
124+
125+ With ` auto_resize: true ` , OpenCode preserves the aspect ratio and scales down
126+ to the dimension limits. It then tries progressively smaller PNG and JPEG
127+ encodings until the Base64 limit is met, so the output media type can change.
128+
129+ ``` text
130+ Input: 4000 × 2000 WebP
131+ Limits: 2000 × 2000
132+ Output: 2000 × 1000 PNG or JPEG
133+ ```
134+
135+ If no encoding fits, processing fails. With ` auto_resize: false ` , an image that
136+ exceeds any limit fails without modification; an image that cannot be decoded
137+ also fails.
138+
139+ ``` text
140+ Input: 2400 × 1600 JPEG
141+ Limit: max_width = 2000, auto_resize = false
142+ Result: Image processing fails
143+ ```
144+
145+ If the image resizer is unavailable, OpenCode passes the original image through
146+ unchanged. Image settings are therefore processing limits, not an upload or
147+ security boundary.
148+
149+ ## Limits
150+
151+ | Limit | Value or behavior | Example |
152+ | ----------------------------- | ------------------------------------------------------------- | -------------------------------------------- |
153+ | Direct attachment | 20 MiB decoded per item; clients may impose lower limits | Two 12 MiB files pass the per-item limit |
154+ | Desktop picker selection | 20 MiB total | Two 12 MiB files exceed the selection limit |
155+ | ` max_base64_bytes ` | Encoded Base64 only, excluding the complete ` data: ` URL | ` SGVsbG8= ` counts as 8 bytes |
156+ | Provider image limits | Apply after OpenCode processing | A provider may reject an accepted image |
157+ | Text attachment model support | Does not require a multimodal model | ` notes.txt ` is inserted as prompt text |
158+ | ` read ` text limits | Uses separate paging and truncation limits | Read a large log in pages |
81159
82- The ` read ` tool recognizes PNG, JPEG, GIF, and WebP by their contents and will
83- ingest at most 20 MiB of source image bytes. It decodes the image and compares
84- its width, height, and encoded Base64 length with all three configured limits.
85-
86- When ` auto_resize ` is ` true ` , OpenCode preserves the aspect ratio, scales the
87- image down to the dimension limits, and tries progressively smaller PNG and
88- JPEG encodings until the Base64 limit is met. The resulting media type can
89- therefore change to PNG or JPEG. If no encoding fits, the tool call fails.
90-
91- When ` auto_resize ` is ` false ` , exceeding any limit fails the tool call without
92- modifying the image. An image that cannot be decoded also fails. If the image resizer cannot be loaded, OpenCode uses the
93- original image instead, so these settings are processing limits rather than an upload or security boundary.
94-
95- ## Limits and provider behavior
96-
97- - Direct prompt attachments are limited to 20 MiB decoded per item by the V2
98- server. Client-specific limits can be lower.
99- - ` max_base64_bytes ` counts the encoded Base64 characters in bytes, not the
100- decoded file size and not the complete ` data: ` URL.
101- - Text attachments are inserted into the prompt as text and do not require a
102- multimodal model. Large text read through the ` read ` tool has separate
103- paging and truncation limits.
104- - Image attachments use provider-native image input. Provider errors can still
105- occur when OpenCode's limits pass but the selected model's limits do not.
106- - PDFs and other unsupported binary prompt attachments should be converted to
107- text or supported images before attaching them.
160+ A client accepting a file does not guarantee that its contents reach the
161+ model. The attachment must use a model-visible format and satisfy both OpenCode
162+ and provider limits.
0 commit comments