Improve error message when xclip/wl-paste is not installed for image paste

[alarmz]

Problem

On Linux, when a user tries to paste an image using Ctrl+V (the chat:imagePaste action) without xclip or wl-paste installed, Claude Code displays:

"No image found in clipboard. Use ctrl+v to paste images."

This is misleading — the clipboard does contain an image, but Claude Code cannot read it because the required tool is missing.

Root Cause

The checkImage command on Linux runs:

xclip -selection clipboard -t TARGETS -o 2>/dev/null | grep -E "image/(png|jpeg|jpg|gif|webp|bmp)" || wl-paste -l 2>/dev/null | grep -E "image/(png|jpeg|jpg|gif|webp|bmp)"

Both xclip and wl-paste fail silently (due to 2>/dev/null), so the grep finds nothing, and Claude Code concludes there is no image.

Interestingly, the copy-to-clipboard failure path already has a helpful message:

"Failed to copy to clipboard. Make sure `xclip` or `wl-copy` is installed on your system and try again."

But the read/paste image path lacks this check.

Expected Behavior

When xclip and wl-paste are both missing, the error message should indicate the actual problem, e.g.:

"Cannot read clipboard image. Please install `xclip` or `wl-clipboard` and try again."

Suggested Fix

Before running checkImage, check if xclip or wl-paste exists in $PATH. If neither is found, show the tool-missing message instead of "No image found in clipboard."

Environment

• OS: Rocky Linux 9 (X11 session)
• Claude Code version: 2.1.62
• Workaround: sudo dnf install xclip

[ShunmeiCho]

For anyone running Claude Code over SSH and hitting clipboard issues — I built cc-clip which installs a lightweight xclip/wl-paste shim on the remote server.

The shim intercepts only the specific invocation patterns Claude Code uses (-selection clipboard -t TARGETS -o and -selection clipboard -t image/* -o), fetches image data from your local Mac through an SSH tunnel, and passes everything else through to the real xclip unchanged.

This means image paste works transparently without modifying Claude Code itself.

[ShunmeiCho]

Related: I built cc-clip which installs a bash shim at ~/.local/bin/xclip (and wl-paste). The shim intercepts exactly the clipboard calls Claude Code makes, fetches image data from your local Mac through an SSH tunnel, and falls back to real xclip/wl-paste for everything else.

cc-clip setup myserver

Setup is one command. No modifications to Claude Code. MIT licensed — happy to hear feedback.

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.