clipaste

Fix screenshot paste in terminal AI tools — locally, over SSH, and in WSL2.

clipaste is a lightweight clipboard daemon for developers who use terminal-based AI coding tools like Claude Code, Codex CLI, and Cursor. Install with one command via Homebrew (macOS) or PowerShell (Windows), and screenshot paste just works — in Ghostty, Alacritty, iTerm2, Kitty, WezTerm, and more. It also bridges your clipboard to remote servers over SSH and to WSL2 environments. Written in Rust, clipaste uses only 9 MB of RAM with 0% CPU overhead.

Problem: You take a screenshot, switch to Claude Code / Codex / Cursor in your terminal, press Ctrl+V — nothing happens. Or you're SSH'd into a remote server and can't paste screenshots at all.

Why: macOS screenshots only put raw image data (TIFF/PNG) on the clipboard. Terminals like Ghostty and Alacritty can only Cmd+V paste text or file URLs — they can't paste raw image data. Over SSH, the remote server has no access to your local clipboard whatsoever.

Solution: clipaste is a tiny background daemon (9 MB RAM, 0% CPU) that:

1. Local paste: Saves screenshots as temp PNG files and registers the file path on the clipboard, so Cmd+V works in terminals. Also adds the legacy PNGf type so Ctrl+V image paste works too.

2. SSH remote paste: Runs an HTTP server on localhost:18340. Use clipaste ssh-setup to configure a remote server — it installs an xclip shim and SSH tunnel so Ctrl+V in remote Claude Code fetches the image from your local machine.

Install

macOS (Homebrew)

brew install hqhq1025/clipaste/clipaste
brew services start clipaste

Windows (PowerShell)

irm https://raw.githubusercontent.com/hqhq1025/clipaste/main/install.ps1 | iex

Build from source

git clone https://github.com/hqhq1025/clipaste.git
cd clipaste
cargo build --release

SSH Remote Paste

clipaste can bridge your local clipboard to remote servers over SSH. One-time setup:

clipaste ssh-setup user@your-server

This automatically:

• Installs an xclip shim on the remote server (~/.local/bin/xclip)
• Adds RemoteForward 18340 to your ~/.ssh/config
• No extra tools needed on the remote server (just curl)

After setup, open a new SSH session and use Ctrl+V in Claude Code / Codex:

ssh user@your-server
claude   # Ctrl+V pastes screenshots from your local Mac

How SSH paste works

Local Mac                          Remote Server (via SSH)
─────────                          ──────────────────────
Screenshot                         Claude Code runs "xclip"
    │                                      │
    ▼                                      ▼
clipaste saves PNG              xclip shim intercepts call
    │                                      │
    ▼                                      ▼
HTTP server ◄──── SSH RemoteForward ────► curl localhost:18340
(:18340)           (tunnel)                    │
    │                                          ▼
    └──── serves PNG ─────────────────► Image delivered ✅

WSL2 Paste

If you run Claude Code / Codex inside WSL2, clipaste bridges the Windows clipboard to WSL2. Run this inside WSL2:

clipaste wsl-setup

This installs the same xclip shim, pointed at clipaste.exe running on your Windows host. No SSH tunnel needed — WSL2 connects directly.

Prerequisites: clipaste.exe must be running on the Windows side (installed via the PowerShell one-liner above).

Windows Host                       WSL2
────────────                       ────
Win+Shift+S screenshot             Claude Code runs "xclip"
    │                                      │
    ▼                                      ▼
clipaste.exe saves PNG          xclip shim intercepts call
    │                                      │
    ▼                                      ▼
HTTP server ◄──── WSL2 network ────────► curl $WIN_HOST:18340
(:18340)        (direct, no tunnel)        │
    │                                      ▼
    └──── serves PNG ──────────────► Image delivered ✅

Paste shortcuts

Tip: Ctrl+V works everywhere (local, SSH, WSL2). Cmd+V is a macOS local-only bonus.

Compatibility

Managing

macOS

brew services info clipaste      # status
brew services restart clipaste   # restart
brew services stop clipaste      # stop

Windows

taskkill /IM clipaste.exe /F                      # stop
Remove-ItemProperty -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Run" -Name "clipaste"  # disable auto-start

FAQ

How do I paste screenshots in Claude Code?

Install clipaste with brew install hqhq1025/clipaste/clipaste && brew services start clipaste on macOS, or the PowerShell one-liner on Windows. Once running, take a screenshot and press Ctrl+V in Claude Code — the image pastes automatically. No configuration needed. clipaste runs as a background daemon and handles the clipboard conversion for you.

Why can't I paste images in my terminal on macOS?

macOS screenshots place raw TIFF/PNG image data on the clipboard, but terminals like Ghostty and Alacritty can only paste text or file paths. clipaste fixes this by intercepting clipboard changes, saving the image as a temp PNG file, and putting the file path back on the clipboard so your terminal can paste it.

How do I paste clipboard images over SSH?

Run clipaste ssh-setup user@your-server once on your local machine. This installs a lightweight xclip shim on the remote server and configures an SSH tunnel. After setup, open a new SSH session and press Ctrl+V in Claude Code or Codex — the image is fetched from your local machine through the tunnel automatically.

Does clipaste work with WSL2?

Yes. Run clipaste wsl-setup inside your WSL2 environment. This installs an xclip shim that connects directly to clipaste.exe on the Windows host — no SSH tunnel needed. After setup, Ctrl+V in Claude Code or Codex inside WSL2 fetches screenshots from the Windows clipboard.

How much memory and CPU does clipaste use?

clipaste uses approximately 9 MB of RAM and 0% CPU when idle. It is written in Rust and runs as a tiny background daemon. On macOS it is managed via brew services; on Windows it auto-starts via a Registry Run key. It has no runtime dependencies beyond the OS clipboard APIs.

Which terminals and AI tools does clipaste support?

clipaste works with Ghostty, Alacritty, iTerm2, Terminal.app, WezTerm, Kitty, and Windows Terminal. It supports Claude Code, Codex CLI, and Cursor CLI. Both Cmd+V (macOS local) and Ctrl+V (all platforms including SSH and WSL2) are supported. See the compatibility tables above for the full matrix.

How is this different from...

• cc-clip — SSH clipboard bridge only. clipaste handles both local paste fix AND SSH bridge in one tool, with no dependencies on the remote server (just curl).
• shotpath — Monitors screenshot files on disk. clipaste works with clipboard screenshots (no file saved to Desktop).
• impaste — A pipe-based tool (impaste | pbcopy). clipaste is fully automatic, no manual step needed.
• pngpaste — Extracts clipboard images to files. clipaste does the reverse: it makes clipboard images available as files for terminals.

Related issues

This fixes a long-standing pain point across multiple projects:

Local paste (macOS/Windows):

• anthropics/claude-code#2102 — Clipboard Image Parsing Failure on macOS
• anthropics/claude-code#17042 — Ctrl+V clipboard paste fails on macOS
• anthropics/claude-code#26901 — Image paste from clipboard no longer works
• openai/codex#6080 — Image pasting issue
• ghostty-org/ghostty#10478 — Support pasting screenshot images

SSH remote paste:

• anthropics/claude-code#5277 — Image paste in SSH/SFTP
• anthropics/claude-code#13738 — Clipboard image paste not working in WSL
• anthropics/claude-code#8324 — Can't paste image from clipboard on Linux

Community

• LINUX DO — Where we first shared this project

License

MIT