From 8580db4416a4307df7397536c4eedd2727330917 Mon Sep 17 00:00:00 2001
From: David Ibia <github@boxpositron.dev>
Date: Fri, 28 Aug 2026 21:47:40 +0000
Subject: [PATCH] feat(bin): add pbcopy/pbpaste shims for headless clipboard
 over OSC 52

Headless servers have no DISPLAY or WAYLAND_DISPLAY, so xclip and xsel
cannot reach a clipboard even when installed. These shims use OSC 52 to
hand text to the terminal emulator on the other end of the SSH connection,
which puts it on the local machine's clipboard.

Inside tmux, pbcopy uses `tmux load-buffer -w -` so the text lands in the
tmux paste buffer and is forwarded outward (requires `set-clipboard on`).
Outside tmux it writes the escape sequence to /dev/tty directly. Both fall
back to xclip/wl-copy when a real display is present.

pbpaste reads the tmux buffer only; terminals refuse OSC 52 reads, since
that would let any remote program siphon the user's clipboard.
---
 .local/bin/pbcopy  | 28 ++++++++++++++++++++++++++++
 .local/bin/pbpaste | 22 ++++++++++++++++++++++
 2 files changed, 50 insertions(+)
 create mode 100755 .local/bin/pbcopy
 create mode 100755 .local/bin/pbpaste

diff --git a/.local/bin/pbcopy b/.local/bin/pbcopy
new file mode 100755
index 0000000..d06ef10
--- /dev/null
+++ b/.local/bin/pbcopy
@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# pbcopy -- macOS-style clipboard copy for this headless box.
+#
+# There is no X/Wayland display here, so xclip/xsel cannot reach a clipboard.
+# Instead we use OSC 52: the text is handed to the terminal emulator on the
+# other end of the SSH connection, which puts it on YOUR machine's clipboard.
+#
+#   ls -la | pbcopy
+#   pbcopy < notes.md
+
+set -euo pipefail
+
+# A real local display (rare here, but free to support).
+if [[ -n "${DISPLAY:-}" ]] && command -v xclip >/dev/null 2>&1; then
+    exec xclip -selection clipboard
+fi
+if [[ -n "${WAYLAND_DISPLAY:-}" ]] && command -v wl-copy >/dev/null 2>&1; then
+    exec wl-copy
+fi
+
+# Inside tmux: load-buffer -w fills the tmux paste buffer and, because
+# set-clipboard is on, forwards OSC 52 out to the terminal emulator.
+if [[ -n "${TMUX:-}" ]] && command -v tmux >/dev/null 2>&1; then
+    exec tmux load-buffer -w -
+fi
+
+# Bare SSH: emit OSC 52 straight at the controlling terminal.
+{ printf '\033]52;c;'; base64 | tr -d '\n'; printf '\a'; } > /dev/tty
diff --git a/.local/bin/pbpaste b/.local/bin/pbpaste
new file mode 100755
index 0000000..ccf0c74
--- /dev/null
+++ b/.local/bin/pbpaste
@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# pbpaste -- companion to pbcopy.
+#
+# Terminals almost universally refuse OSC 52 *reads* (it would let any remote
+# program siphon your clipboard), so this cannot see your local clipboard.
+# What it can do is echo back the tmux paste buffer, i.e. whatever pbcopy or
+# a tmux copy-mode yank last put there.
+
+set -euo pipefail
+
+if [[ -n "${DISPLAY:-}" ]] && command -v xclip >/dev/null 2>&1; then
+    exec xclip -selection clipboard -o
+fi
+if [[ -n "${WAYLAND_DISPLAY:-}" ]] && command -v wl-paste >/dev/null 2>&1; then
+    exec wl-paste
+fi
+if [[ -n "${TMUX:-}" ]] && command -v tmux >/dev/null 2>&1; then
+    exec tmux save-buffer -
+fi
+
+echo "pbpaste: no readable clipboard (not in tmux, no display)" >&2
+exit 1