clipaste

# clipaste

> A lightweight Rust clipboard daemon that makes screenshot paste work in terminal-based AI
> coding tools (Claude Code, Codex CLI, Cursor CLI) on macOS and Windows, and bridges
> the clipboard across SSH and WSL2 boundaries. Graphical Linux hosts provide
> read-only PNG capture for the SSH bridge. MIT licensed.

clipaste exists because of a specific, verifiable gap: a macOS screenshot places only
raw image bytes (TIFF/PNG) on the pasteboard, and terminals such as Ghostty and
Alacritty can paste text and file paths but have no mechanism for handing raw image
bytes to the program they host. The keystroke arrives carrying nothing. Over SSH the
remote has no access to the local clipboard at all, so tools fall back to inserting the
local file path as literal text — a path that does not exist on the remote.

On macOS/Windows, clipaste watches the clipboard, saves each screenshot as a PNG,
and adds a path alongside the image data. Linux reads PNG without changing the
clipboard. Each host serves the staged PNG on
`127.0.0.1:18340`, so a remote reachable through an SSH RemoteForward tunnel can fetch
the picture rather than a meaningless path.

## Install

The daemon supports macOS, Windows, and graphical Linux with usable clipboard
access. Linux hosting reads `image/png` only; it does not add local text-path paste.

| OS / context | Local clipboard-host daemon | Consumer of another host's clipboard |
|---|---|---|
| macOS | Supported | SSH remote via `clipaste-paste` |
| Windows | Supported | Via WSL2 |
| Native Linux desktop | Read-only PNG via Wayland data-control or X11/XWayland | Supported over SSH via shims / `clipaste-paste` |
| Headless Linux | No display; host startup fails with guidance | Supported with configured helpers / SSH |
| WSL2 | No; the Windows daemon is required | Supported via `wsl-setup` |

- macOS: `brew install hqhq1025/clipaste/clipaste && brew services start clipaste`
- Windows: `irm https://raw.githubusercontent.com/hqhq1025/clipaste/main/install.ps1 | iex`
- Verify: `clipaste doctor` (add `--json` for machine-readable output)
- SSH remote: `clipaste ssh-setup user@host`, run on the local macOS, Windows, or graphical Linux clipboard host with its daemon running
- WSL2: `clipaste wsl-setup` — run this inside the distro, with clipaste.exe running on Windows
- Server-only mode: set `CLIPASTE_SERVER_ONLY=1` in the macOS/Windows daemon's
  environment when the user only pastes remotely or GUI apps paste a path instead
  of the image. The clipboard is left as copied, images are still served over
  HTTP, and local terminals get no path. `doctor` reports `server-only` in its
  `daemon` check; `brew services` cannot set the variable, so macOS needs a user
  LaunchAgent (see the README)

Linux release archives (since v2.5.0) include static x86_64 and ARM64 binaries.
Install distro tools first (Ubuntu example):

```bash
sudo apt install wl-clipboard xclip curl
```

Download the matching `x86_64-unknown-linux-musl` or
`aarch64-unknown-linux-musl` archive from the v2.6.0 release, verify it against
`SHA256SUMS`, and extract it. Then:

```bash
install -Dm755 clipaste "$HOME/.local/bin/clipaste"
export PATH="$HOME/.local/bin:$PATH"
clipaste
```

For source installation with Rust/Cargo:
`cargo install --git https://github.com/hqhq1025/clipaste --tag v2.6.0 --locked`.
Source installs use `~/.cargo/bin`; extracted binaries above use `~/.local/bin`.
Keep the relevant directory on `PATH`. Run `clipaste`
as your desktop user from a graphical terminal and leave it running. No Linux
service or auto-start is installed. In a separate terminal in the same session:

```bash
clipaste doctor --json
clipaste ssh-setup user@host
```

Linux builds retain diagnostics and consumer setup, including `wsl-setup`.
Consumer shims fetch from HTTP; the Linux host resolves real system clipboard
tools, not the generated shims.

## Linux backend contract

- `CLIPASTE_BACKEND=auto` (default): prefer system `wl-paste` with usable
  data-control access; otherwise warn and use system `xclip` through an
  accessible `DISPLAY`, or fail with actionable guidance if unavailable.
- Native Wayland requires `wl-clipboard >=2.2` for empty-selection watch events.
  All Wayland clipboard accesses use `wl-paste --watch` in bounded one-shot mode,
  which refuses popup fallback and verifies actual compiled-in data-control
  support. Ext-only compositors need `wl-clipboard >=2.3` built with
  `ext-data-control` support; `wlr-data-control` works with compatible 2.2+
  builds. Version 2.1.x triggers the `auto` XWayland fallback or fails without
  `DISPLAY`.
- `CLIPASTE_BACKEND=wayland` requires native data-control access and fails instead
  of falling back. `CLIPASTE_BACKEND=x11` requires `xclip` and an accessible
  `DISPLAY`. Apply the same override to the daemon and `doctor`.
- No display fails with guidance to run from a graphical desktop or configure a
  consumer. Wayland-only without data-control fails with guidance to use an
  XWayland clipboard bridge (`xclip` + `DISPLAY`) or an X11 session. No forced-focus
  polling or popup workaround is used.
- GNOME Wayland may need the XWayland clipboard bridge. Reporters must test a
  screenshot copied from a native Wayland app, re-run `doctor`, and verify the
  image fetched by `clipaste-paste` in a new SSH session. An X11-only test does
  not prove native Wayland support; universal compatibility has not been tested.
- Linux polls every 300 ms: clipboard `image/png` -> private stable PNG cache ->
  existing loopback HTTP -> SSH shims / `clipaste-paste`. It adds no file URLs
  or text to the clipboard and makes no promise of local terminal text-path
  paste. Image file-copy offering only a URI is not supported yet.
- Clipboard clears, non-image content, and recognized private markers clear the
  staged image; historical cached paths remain. The cache is private (`0700`
  directories, `0600` files) and has no automatic expiry.
- Existing macOS/Windows paste workflows are unchanged. Linux verification
  does not establish macOS/Windows regression coverage.

## Paste gesture by tool and location

| Tool | Local (macOS / Windows) | SSH → Linux | SSH → macOS | WSL2 |
|---|---|---|---|---|
| Claude Code | Ctrl+V | Ctrl+V | `clipaste-paste` | Ctrl+V |
| Cursor CLI | Ctrl+V | Ctrl+V | `clipaste-paste` | Ctrl+V |
| Codex CLI | Ctrl+V | `clipaste-paste` | `clipaste-paste` | `clipaste-paste` |

Codex CLI reads the clipboard in-process via the `arboard` crate, so it never executes
the `xclip` binary and cannot be intercepted by a shim. `clipaste-paste` writes the
clipboard image to a real file on the current host and prints the path; hand that path
to the tool.

Never press Cmd+V inside an SSH session — it sends the local file path as text.

## For coding agents

`clipaste doctor --json` is the machine-readable entry point. Its role contract is
`clipboard-host`, `ssh-remote`, `wsl2`, or `unsupported-host`. Each check is
`{name, status, detail, fix}`; `fix` is a remediation command, guidance, or `null`.
Exit code: 0 usable (including warnings), 1 broken, 2 bad arguments. All setup
commands are non-interactive and idempotent.

WSL takes precedence over SSH and remains a Windows consumer even with display
variables. Actual SSH sessions, including SSH into macOS or graphical Linux,
remain `ssh-remote`. Graphical local Linux is `clipboard-host`; configured
headless Linux consumers retain `ssh-remote` without SSH environment variables.
Headless Linux without consumer indicators gets `clipboard-host` diagnostics
with a failing `backend` check and graphical-session guidance.
`unsupported-host` remains in the contract for platforms without a backend;
it is not a blanket Linux classification.

Run Linux host diagnostics as the same desktop user/session as the daemon:
Wayland needs `WAYLAND_DISPLAY` and `XDG_RUNTIME_DIR`; X11/XWayland needs `DISPLAY`
and display authorization. Preserve the same `CLIPASTE_BACKEND`. SSH, `sudo`,
stale tmux sessions, and services can lack this context. Setting a display
variable alone does not grant access. Follow the reported tool/session/protocol
remedy; neither installing `curl` nor adding a service supplies desktop access.
An empty clipboard warning is normal before copying a screenshot.

## Key facts

- Written in Rust; Linux requires system clipboard tools, and CLI HTTP uses `curl`
- Existing macOS/Windows footprint: ~9 MB resident memory, no measurable idle CPU;
  this is not a Linux measurement, since Linux polls and invokes system tools
- macOS: NSPasteboard change-counter watcher. Windows: event-driven via `AddClipboardFormatListener`, no polling
- Linux: read-only PNG polling every 300 ms; does not rewrite clipboard formats
- HTTP server binds to `127.0.0.1` only and is never exposed to the network
- Screenshots use stable local SHA-256 cache paths with no automatic expiry;
  identical images reuse a path. Storage grows with unique images, and manual
  deletion invalidates saved paths.
- WSL2 host detection probes candidate addresses rather than reading `/etc/resolv.conf` alone, so `networkingMode=mirrored` and NAT both work
- Terminals: Ghostty, Alacritty, iTerm2, Terminal.app, WezTerm, Kitty, Windows Terminal

## Opt-in Linux verification

Run `bash tests/linux/run.sh` from the repository root on Linux for real
clipboard-tool tests in isolated Xvfb/headless Sway sessions. Tests use temporary
HOME/cache/runtime directories, not the real user's clipboard. See `AGENTS.md`
for prerequisites and the `tests/linux/Dockerfile` container recipe. This does
not replace testing a screenshot from a native app on the reporter's compositor.

## Links

- [Homepage](https://hqhq1025.github.io/clipaste/)
- [Source and README](https://github.com/hqhq1025/clipaste)
- [AGENTS.md — install recipe for coding agents](https://github.com/hqhq1025/clipaste/blob/main/AGENTS.md)
- [Releases](https://github.com/hqhq1025/clipaste/releases)
- [Issue tracker](https://github.com/hqhq1025/clipaste/issues)
- [Full text for retrieval](https://hqhq1025.github.io/clipaste/llms-full.txt)