Paste local clipboard images into remote CLI sessions over SSH.

clipboard-ssh is macOS-first. It lets you copy an image on your Mac, press a global hotkey, upload the image to a remote machine over SSH, and paste a remote file reference into the currently focused terminal prompt.

No remote daemon, plugin, or OpenCode server is required.

1. You copy an image on macOS.
2. You focus a terminal prompt connected to a remote machine.
3. You press Ctrl+Option+Cmd+V.
4. Hammerspoon runs clipboard-ssh-image locally.
5. The helper saves the clipboard image with pngpaste.
6. The helper uploads the PNG to the configured remote directory with scp.
7. Hammerspoon pastes a text reference like this into the focused app:

 @/home/ubuntu/.clipboard-ssh-uploads/clip-20260508-220000-....png

The CLI you are using must understand local file references such as @/path/to/image.png. OpenCode does. Other tools may use different syntax.

• macOS
• Homebrew
• SSH access to a remote machine
• A writable absolute directory on that remote machine
• Hammerspoon Accessibility permission for synthetic paste

The setup script installs these if missing:

• pngpaste
• Hammerspoon

./setup-macos.sh

Or run non-interactively:

CLIPBOARD_SSH_REMOTE=exos \
CLIPBOARD_SSH_REMOTE_DIR=/home/ubuntu/.clipboard-ssh-uploads \
./setup-macos.sh

For nonstandard SSH ports or advanced SSH options, create an alias in ~/.ssh/config and use that alias as CLIPBOARD_SSH_REMOTE.

1. Copy an image to the macOS clipboard.
2. Focus your terminal prompt.
3. Press Ctrl+Option+Cmd+V.
4. Press Enter yourself when ready.

The hotkey does not auto-submit the prompt.

The setup script writes:

~/.clipboard-ssh/config

Example:

CLIPBOARD_SSH_REMOTE=exos
CLIPBOARD_SSH_REMOTE_DIR=/home/ubuntu/.clipboard-ssh-uploads
CLIPBOARD_SSH_PREFIX=' @'

The helper is installed to:

~/.local/bin/clipboard-ssh-image

The Hammerspoon module is installed to:

~/.hammerspoon/clipboard_ssh.lua

The setup script appends a marked block to:

~/.hammerspoon/init.lua

With an image on your clipboard:

~/.local/bin/clipboard-ssh-image --stdout

Expected output:

 @/absolute/remote/path/to/clip-....png

Logs are written to:

~/Library/Logs/clipboard-ssh.log

If the hotkey shows an upload alert but does not paste, enable Hammerspoon in:

System Settings -> Privacy & Security -> Accessibility

If the upload times out, make sure your SSH target works without a password prompt. The hotkey path is non-interactive by design so it does not hang behind a hidden SSH prompt.

If no image is found, copy an actual image to the clipboard. Text URLs or HTML image selections are not always image clipboard data. Screenshots copied with Cmd+Ctrl+Shift+4 work well.

• macOS: supported
• Linux: planned
• Windows: planned