Troubleshoot Vision Paste Across Desktop, WSL, and SSH

Image paste depends on the terminal, operating system, display server, and whether Hermes runs locally or across SSH. Start by identifying that environment instead of repeatedly pressing the same shortcut.

Use the most reliable local path first

The explicit /paste command is the best first fallback when the terminal intercepts normal paste behavior. Hermes checks the local clipboard and attaches an image when one is available.

Normal Ctrl+V or Cmd+V uses a layered paste flow that prefers text, then clipboard fallbacks, then image or image-path attachment when supported. Local IDE terminals can also use Hermes keyboard integration when the IDE intercepts command keys.

Match the environment

macOS local: use /paste when Cmd+V or the terminal turns the screenshot into a path.
Linux X11: clipboard support depends on the local clipboard utilities documented for the current release.
Linux Wayland: the local environment generally needs wl-paste from the Wayland clipboard package.
WSL2: Hermes can use the Windows clipboard through PowerShell when running in a supported local WSL terminal.
Local VS Code, Cursor, or Windsurf: IDE integration can improve key handling, but it is local-machine functionality.
SSH: the remote process cannot directly read the local graphical clipboard. Transfer the image deliberately, then attach the remote file path with the supported image command.

Do not run local IDE integration commands inside an SSH session and expect them to control the machine in front of you.

Troubleshooting checklist

Confirm Hermes is local or remote.
Identify macOS, X11, Wayland, WSL2, or an IDE terminal.
Try /paste before installing extra software.
Confirm the clipboard contains an image, not only copied HTML or text.
Check required local clipboard utilities.
For SSH, transfer a redacted image intentionally.
Confirm the model or auxiliary route supports vision.

Common pitfalls

Treating OSC52 text transport as remote image transport

A terminal may move clipboard text across a remote session without giving the remote process direct access to local image pixels.

Installing the wrong clipboard utility

X11 and Wayland use different clipboard paths. Identify the display server first.

Pasting a private full-screen capture to test mechanics

Use a harmless sample image until attachment and provider routing are proven.

Verification steps

Attach a small harmless image using /paste or the documented file path command.
Confirm the image badge appears before submission.
Ask for one obvious visual fact.
Confirm the response uses the image rather than guessing from the filename.
Repeat only with the real, redacted screenshot after the harmless test succeeds.
Check the local images directory if the expected attachment is missing or stale.

Official reference

See Vision & Image Paste for the current platform matrix and supported commands.