I built sshpic because local screenshots stop at the SSH boundary

#opensource #cli #macos #productivity

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 mean authentication information, such as passwords, API keys, or access tokens.