I built sshpic because local screenshots stop at the SSH boundary

I often run coding agents inside a remote SSH session from iTerm2 on my Mac. The annoying part was not text input. It was screenshots.

The screenshot is on my local Mac clipboard, but the coding agent is running inside a remote SSH terminal. So the normal flow became: screenshot → save file → scp somehow → copy remote path → return to the agent → paste path. That felt too slow for a workflow that happens many times a day.

I wanted this instead: copy local screenshot → focus remote coding agent in iTerm2 → Cmd+V → remote image path appears. So I built sshpic.

What sshpic does

When you press Cmd+V inside an iTerm2 SSH session:

• It reads the local Mac clipboard.
• If the clipboard contains an image, it uploads the image to the remote SSH host.
• It inserts the remote image path into the active iTerm2 session.
• If the clipboard contains text, normal text paste behavior is preserved.

In other words, it turns the screenshot handoff into a normal paste action.

Why this exists

This is for a narrow but painful workflow:

• you are on macOS
• you use iTerm2
• you connect to a remote machine over SSH
• you run a terminal coding agent there
• you want to paste a local screenshot without leaving the coding session

CLI means Command Line Interface, a tool used from the terminal.
SSH means Secure Shell, a protocol for connecting to a remote machine.
SCP means Secure Copy, a file transfer command that copies files over SSH.
AI means Artificial Intelligence, software behavior produced by machine learning systems.

v0.1 scope

The first release is intentionally narrow:

• Mac + iTerm2 first
• real SSH + Codex E2E verified
• no cloud upload
• no remote install
• SSH-only transfer
• no per-screenshot upload command
• text paste fallback verified
• restore supported

E2E means End-to-End, a full real user workflow test.

Important limitation

sshpic does path insertion, not native AI image attachment. It guarantees that the image exists on the remote SSH host and that the remote image path is inserted into the active iTerm2 session. The terminal AI tool must separately know how to use that path.

So this is not a claim that every AI tool will natively understand the image. It is a small tool for getting the image onto the remote host and inserting the path where you are already typing.

Security notes

The design goal is to avoid cloud upload and avoid installing anything on the remote machine. The image is transferred over SSH. Remote files are written with restrictive permissions.

Still, screenshots can contain sensitive information. Be careful with screenshots that include tokens, secrets, credentials, private messages, or internal dashboards.

Credentials means authentication information, such as passwords, API keys, or access tokens.

Project link

https://github.com/leekyungmoon/sshpic

Feedback from people using remote SSH coding-agent workflows would be very useful. If this saves you the screenshot → scp → paste path loop, a star helps other remote SSH users find it.