03. Giving the Assistant Context

Images

A screenshot in the prompt is often clearer than a paragraph describing the dialog.

Concept

Matcha CLI accepts pictures as prompt attachments: a clipboard image, a file you copied in the file manager, or a file you dragged from Finder / Files / Explorer. Each one becomes an [Image #N] chip. The bytes are saved into that session’s images/ folder under ~/.matcha/sessions/ so the picture is still there after you send and if you resume later.

A prompt can hold up to 10 image chips. Each side must be at least 8 pixels. JPEG, PNG, and WebP are the formats that survive send and resume. GIF, BMP, and TIFF are rejected.

Why this matters

Error dialogs, design mocks, and whiteboard photos do not transcribe well. Paste or drop the picture, write what you want done, and send.

If the picture is already a file in the repo, @ is enough — you do not need a chip. Use an image chip when the pixels live on the clipboard or outside the workspace.

How to add an image

Action	macOS	Linux	Windows
Drag an image from the file manager into the prompt	Finder	Files / Dolphin	Explorer
Copy a file in the file manager, then paste	`Cmd+V`	`Ctrl+V`	`Ctrl+V`
Screenshot or “Copy Image,” then paste	`Cmd+V`	`Ctrl+V`	`Alt+V`

Cmd+V / Ctrl+V also work (Super+V is the same family). On Windows, Windows Terminal’s default Ctrl+V pastes text only and silently drops a screenshot clipboard. Alt+V is the Matcha CLI shortcut that reaches the image. To make Ctrl+V paste images too, add this to actions in Windows Terminal settings.json:

{ "command": null, "keys": "ctrl+v" }

Non-image files from a drop or a file-manager copy insert their absolute path as text, not a chip.

After the chip appears

The chip label is [Image #N]. Numbers increase for the life of the draft; they do not reuse a gap if you delete one.
Enter on the chip opens a preview (it does not send). Preview needs a terminal that can draw inline images. Otherwise you get Image rendering not supported in this terminal, or Inline images disabled within tmux.
Write a caption around the chip (what’s wrong with [Image #1]) and press Enter off the chip to send.

What a bad image looks like

Matcha CLI tells you with a toast. Nothing is inserted when the paste is rejected.

What you see	What it means
`Image too small (W×H). Must be at least 8×8 pixels.`	Either side is under 8 px.
`Image limit reached (max 10)`	The draft already has ten chips. Extra drops are skipped.
`Couldn't save pasted image`	The session could not write the file under `~/.matcha/sessions/…/images/`.
`Couldn't load image preview`	The chip is there, but the preview decoder failed.
`Images can't be attached when editing a shared queued prompt`	Queue edit from another client; text is fine, images are not.

A file that is not a real image (truncated PNG, random bytes, or a format the model will refuse) never becomes a chip, or is stripped when the session is loaded again so a later turn does not fail on it. If paste does nothing and you expected a picture, check that the clipboard actually holds an image and that you used the shortcut in the table above.