Agent.Space Blog

Paste Images into Claude Code over SSH: A File-First Workflow

Get a local screenshot into remote Claude Code: save the image, transfer it over SSH, verify its remote path, and distinguish file input from clipboard sync.

When Claude Code runs on another computer through SSH, an image in your laptop's clipboard is not automatically a file on that computer. Pasting a path such as /Users/me/Desktop/error.png does not transfer the image either.

The dependable starting point is to save the screenshot, transfer it to the remote host, verify the destination, and give Claude that remote path. This guide assumes you already have authorized SSH access; it does not require a clipboard-bridge plugin.

Save a small, non-sensitive image

Crop the screenshot to the relevant interface or error. Remove account details, tokens, customer information, and unrelated windows. Keep an original privately if needed, but transfer only what the task requires.

For the commands below, save the sanitized image as claude-shot-01.png in your current local directory. Use a new name if that file already exists remotely, because copying to the same destination can overwrite it.

If you are still moving the rest of the project, follow the remote Mac migration checklist. A transferred repository does not necessarily contain screenshots saved elsewhere on your laptop.

Transfer the image from your local terminal

Run this on your laptop, not inside the remote SSH session:

bash
scp ./claude-shot-01.png user@remote-host:claude-shot-01.png

Replace user@remote-host with your authorized account and host, or your configured SSH host alias. The destination in this example is a file in that remote user's home directory, not necessarily your project folder.

The command uses OpenSSH's secure file-copy tool. Confirm the expected host before trusting a new host-key prompt. Do not disable host verification to make the transfer work. If your environment uses a non-default port or managed access method, use its approved connection configuration.

Windows users can use the same example from a terminal where OpenSSH's scp is installed and the current directory contains the image. If it is unavailable, use an approved SFTP client; installing an unknown clipboard helper is not required.

Verify the remote file before asking Claude

In the SSH terminal on the remote computer:

bash
ls -lh ~/claude-shot-01.pngfile ~/claude-shot-01.png

Check that a non-empty image exists. These checks establish file presence and type, not that Claude can see it or that it is the intended screenshot.

Move or copy it into the intended project's materials folder if the task should retain it there. Use the actual resulting path in Claude Code. The official image workflow supports supplying an image path.

Start with a narrow instruction: ask Claude to open the image and describe one distinctive, non-sensitive element before making code changes. If the project permissions prevent access outside its folder, put the image in the approved project directory instead of widening filesystem access.

Diagnose the stage that failed

SymptomNext check
Pasting shows only text or a local filenameWhether the image was actually transferred
scp cannot find the sourceThe local directory and filename
Transfer succeeds but Claude cannot find the imageThe remote account, destination, and actual project path
A file exists but does not open as an imageThe format and contents, not just the extension
Claude describes the wrong screenshotThe selected host, file, and whether an older copy was overwritten

Clipboard bridges may make repeated transfers more convenient, but they add software and a data path to review. Do not assume every terminal or remote-control tool transfers image clipboards. Copying text successfully does not establish image support.

The steps above have been checked against documentation, not tested against your SSH host or model account.

Use Agent.Space when you want a task interface

For an editable Agent.Space conversation, provide the image as a task attachment and confirm which computer and folder the task uses. If the image must remain part of the project, ask the Agent to save it in the materials folder, then verify the file. The computer and file-location guide explains why conversation attachments and persistent project files are different.

A read-only synced conversation cannot accept a new task just because its old images are visible. Open the intended controllable conversation before adding materials.

Open Agent.Space to start with one sanitized image and a read-only inspection request. If you need to operate the remote Mac's actual desktop, review Remote Screen instead; check the chosen client rather than assuming its clipboard works like SSH.