Clipboard history for Linux and macOS — everything you've copied, one shortcut away,
with end-to-end-encrypted sync between your machines.
Install · Features · Shortcuts · Device sync · Troubleshooting · Security · Project page
Press a global shortcut and a strip of tiles slides up from the bottom of the screen showing everything you've recently copied — text, images, and files. Click a tile, or press Enter, to load it back onto the clipboard.
It stays out of your way: a paperclip in the menubar or system tray, never in the dock. And because the same history engine runs on both platforms, an end-to-end-encrypted LAN sync keeps your clipboard with you as you move between machines — including between Linux and macOS.
Linux — Wayland, here on COSMIC. Custom tabs, type badges, and the shortcut bar along the bottom. The panel looks the same on Hyprland/Omarchy, in that desktop's own theme colours.
macOS — the same panel, showing clips that synced over from the Linux machine above.
The same panel and history engine run on both platforms:
- Bottom panel of tiles for recent text, images, and files, summoned by a global shortcut and dismissed by clicking away or pressing Esc.
- Previews — images show inline; files and documents show a type tile, with thumbnails for images, videos, PDFs and docs.
- Pin items so they survive pruning and sort first; search by typing; keyboard navigation and quick-select.
- Tabs — Recent, ★ Pinned, and your own colored, named custom tabs; pin a clip and choose which tab it lands in.
- Type filter — show only one kind at a time (text / image / video / audio / PDF / spreadsheet / archive / other), with per-type colored badges.
- Plain vs. rich paste — strip formatting, or keep it when the source had it. Right-click a tile to copy as plain text.
- Keeps the clipboard (Linux) — closing the app you copied from no longer empties the clipboard: Clippy puts the clip back, the way Klipper does on Plasma, on any Wayland desktop. Clips a password manager marks as sensitive are never put back. Toggle in Settings.
- History retention — keep for 1 day / 1 week / 1 month / 1 year / forever, with automatic pruning, plus a manual Clear history.
- Live updates — an open panel refreshes as new clips arrive, including ones pushed from a synced peer.
- Follows the OS light/dark theme automatically.
- Encrypted LAN sync (opt-in) — share the clipboard across paired devices: text, images, and any file, with previews and a size cap you control.
- Local-only storage — SQLite + files under your data dir; nothing leaves your machine unless you pair devices for sync.
- Diagnosable —
clippy typesshows what the clipboard is actually offering and how Clippy would file it;CLIPPY_DEBUG=1traces every capture and restore. See When a clip won't paste.
Each platform integrates natively:
- Linux: a system-tray paperclip, a full-screen click-away overlay, and a
shortcut Clippy binds for you in your desktop's own config — COSMIC's
custom shortcuts, Hyprland/Omarchy's
bindings.lua, or KDE Plasma's global shortcuts. It follows that desktop's light/dark mode and its palette. - macOS: a menubar paperclip, QuickLook thumbnails, and the icon of the app each clip came from on every tile (a Wayland security boundary makes that last one macOS-only — see Limitations).
Requires Wayland — specifically a compositor offering wlr-layer-shell and
ext-/wlr-data-control. COSMIC, Hyprland and Sway all qualify; a plain GNOME
Wayland session does not. Developed on Pop!_OS 24.04 + COSMIC and
Omarchy 4 (Arch + Hyprland).
Two independent things decide your setup, so they're covered separately below: your distro picks the package, and your desktop picks the integration — where the shortcut is written, which tray hosts the paperclip, which theme Clippy follows. Arch with COSMIC and Debian with Hyprland are both fine.
APT repository (recommended) — add it once, then install and update with
apt like any system package:
curl -fsSL https://davidboulay.github.io/Clippy/clippy.gpg | sudo tee /usr/share/keyrings/clippy.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/clippy.gpg] https://davidboulay.github.io/Clippy ./" | sudo tee /etc/apt/sources.list.d/clippy.list
sudo apt update && sudo apt install clippyNew versions then arrive with sudo apt upgrade. The repo is GPG-signed and
served over GitHub Pages. Or grab the .deb directly from the
Releases page:
gh release download --repo davidboulay/clippy --pattern '*.deb'
sudo apt install ./clippy_*.debOmarchy, EndeavourOS and the other Arch derivatives are covered here too — they
share pacman, and nothing in the package is derivative-specific.
There is no published binary package or AUR entry yet, so build it from the
tree — makepkg does the work and pacman resolves the dependencies:
git clone https://github.com/davidboulay/Clippy.git && cd Clippy
make arch # → packaging/arch/clippy-<ver>-any.pkg.tar.zst
sudo pacman -U packaging/arch/clippy-*.pkg.tar.zstEverything Clippy needs is in the official repos — nothing from the AUR. The
package is arch=('any'): it installs to /usr/lib/clippy rather than
site-packages, so an Arch Python minor bump can't break it.
Optional features are optdepends, left out of a minimal install. For LAN sync:
sudo pacman -S python-pynacl python-zeroconf python-spake2Updating: rebuild and pacman -U again. Clippy will not try to update
itself here — it detects a pacman install and shows the command to run instead
of an install button, because driving apt over a pacman install would corrupt
both package databases.
- From source (any Wayland distro):
git clone … && cd Clippy && ./scripts/install.sh— detectspacman,apt-getordnf, installs the dependencies, drops a~/.local/bin/clippylauncher + icon, enables autostart and starts the daemon. - AppImage (experimental):
make appimage, then rundist/Clippy-*.AppImage. - Flatpak / COSMIC Store: ❌ not viable — COSMIC withholds the privileged
layer-shellanddata-controlWayland protocols from Flatpak-sandboxed apps, which Clippy requires. Details inFLATHUB.md.
Your package manager handles these; the list is here for source installs.
| Arch | Debian / Ubuntu | |
|---|---|---|
| Required | python-gobject gtk3 gtk-layer-shell libayatana-appindicator wl-clipboard |
python3-gi gir1.2-gtk-3.0 gir1.2-gtklayershell-0.1 libgtk-layer-shell0 gir1.2-ayatanaappindicator3-0.1 libayatana-appindicator3-1 wl-clipboard |
| LAN sync | python-pynacl python-zeroconf python-spake2 |
python3-nacl python3-zeroconf python3-spake2 |
| Copy sound | pipewire or libpulse |
pipewire-bin or pulseaudio-utils |
| Notifications | libnotify |
libnotify-bin |
| Thumbnails | ffmpeg (video), poppler (PDF) |
ffmpeg, poppler-utils |
| XWayland paste fallback | xclip, gtk4 |
xclip, libgtk-4-1 |
This part follows your desktop, not your distro. clippy status prints the
one it detected.
Shortcut. Open the tray icon → Settings (or the ⚙ in the panel), click
the shortcut button, and press your combo. Clippy writes the binding into
whichever config your desktop actually reads. The desktop is the one your
session names in XDG_CURRENT_DESKTOP; a left-over ~/.config/cosmic or
~/.config/hypr only counts when that is unset:
| Desktop | Where the binding goes |
|---|---|
| COSMIC | ~/.config/cosmic/…/Shortcuts/v1/custom, with a one-time backup of your existing shortcuts |
| Omarchy | a marked block in ~/.config/hypr/bindings.lua, then hyprctl reload |
| Hyprland (plain) | ~/.config/hypr/clippy.conf, sourced once from hyprland.conf, then hyprctl reload |
| KDE Plasma | Plasma's own global shortcuts (kglobalaccel, live, no file edits): the launch shortcut of Clippy's app entry, the same one System Settings → Shortcuts shows, so either side can change it |
| anything else | nothing is written — clippy setup-shortcut prints what to bind by hand |
To see the steps for your desktop from the terminal: clippy setup-shortcut.
On Omarchy, pick a free key. Super+V is Universal paste and Super+Ctrl+V is Omarchy's own clipboard manager. Super+Shift+V is free by default. Check with
omarchy menu keybindings --print; Clippy emits anhl.unbindabove its own bind, so it overrides cleanly if you do reuse a key.
Tray. The paperclip needs an SNI host on your panel — COSMIC's Status
Area applet, or the omarchy.tray widget in ~/.config/omarchy/shell.json
(it ships enabled). Without one the panel's ⚙ still opens Settings and the
shortcut still works.
Theme. Clippy follows the desktop's light/dark and its palette: COSMIC's
theme files, or the active Omarchy theme's colors.toml; anything else falls
back to the XDG portal for light/dark and Clippy's built-in palette. A running
Clippy restyles itself when you switch themes — no restart.
A native menubar app; the panel opens on ⌘+⇧+V
(no Accessibility permission needed — the hotkey uses Carbon RegisterEventHotKey).
Grab Clippy-<ver>.dmg from the
Releases page and
drag Clippy to Applications. Or build it yourself on a Mac:
git clone https://github.com/davidboulay/clippy.git && cd clippy
./packaging/macos/build-app.sh --dmg # → dist/Clippy.app and dist/Clippy-<ver>.dmgThe build is ad-hoc signed (no Apple Developer ID), so the first launch needs
right-click → Open once (or xattr -dr com.apple.quarantine /Applications/Clippy.app).
See packaging/macos/README.md.
Updating: open Settings → Check for updates. When a newer release exists
the button becomes Download <version> — clicking it downloads the new
.dmg, swaps the app in place, and relaunches automatically (no manual
re-download or drag). A Linux .deb install updates the same way via Settings
→ Check for updates; a pacman or source install shows the command to run
instead, since only the .deb can be upgraded safely from inside the app.
| Action | Linux | macOS |
|---|---|---|
| Open / close the panel | your shortcut (see above) | ⌘+⇧+V |
| Search history | type | type |
| Move between tiles | ←/→/↑/↓ | ←/→ |
| Copy selected & close | Enter | Enter |
| Copy the Nth tile | Ctrl+1…9 | ⌘+1…9 |
| Pin / unpin selected | Ctrl+P | ⌘+P |
| Delete selected | Delete | ⌘+⌫ |
| Close | Esc / click away | Esc / click away |
| Copy as plain text | right-click tile | right-click tile |
Selecting a tile sets the clipboard — then paste with Ctrl/⌘+V yourself (Clippy never injects keystrokes).
"Click away" works differently per compositor, and it shows. On cosmic-comp the panel is a bottom strip that leaves the rest of the screen live: it closes when your click moves the keyboard focus, and that click still lands where you aimed it. On wlroots compositors (Hyprland/Omarchy) focus is no signal — it follows the mouse and it follows window activation, so a panel that trusted it vanished when the pointer merely crossed a window and stayed put when you clicked the window that already had focus. There the panel covers the screen instead, invisible except for the strip, and reads the click itself — so the click that dismisses it is consumed, and the bar is not clickable while it is open.
Most clipboard sync is either locked to one ecosystem or routed through a cloud:
- Apple Universal Clipboard only works between Apple devices signed in to the same Apple ID, over Continuity.
- Cloud clipboard managers copy your clipboard — passwords, tokens, snippets — onto someone else's servers.
Clippy's sync is local-first and end-to-end encrypted: devices talk directly to each other on your own network, with no cloud and no account. It's built for the setups Universal Clipboard can't cover:
- A Linux machine and a Mac (or any mix) — copy on one, paste on the other.
- Two Apple devices on different Apple IDs — e.g. a work Mac and a personal Mac — where Continuity won't bridge them.
- Anyone who simply doesn't want clipboard contents leaving their LAN.
If all your devices are Apple and share one Apple ID, you may not need this — Continuity already does it. Clippy's sync is for everyone else.
- What syncs: text, images, and any file (video, PDF, …). Files arrive as the real file (right name + type); images and videos show a preview tile.
- Discovery: automatic via mDNS (zeroconf); falls back to a manual IP if your network blocks multicast.
- Security: each device has a long-term X25519 identity key (stored
0600). Pairing runs SPAKE2 (a password-authenticated key exchange) keyed by a 6-digit code — neither side transmits the code or anything an eavesdropper could crack, and a wrong code cannot complete pairing, so a man-in-the-middle can't slip in a key. Every payload is encrypted + authenticated with NaCl. Only paired devices are accepted, and traffic never leaves the LAN. Trust is keyed to the stable identity key, so it survives a device's id changing. - Device status: a green/grey bulb per paired device shows real reachability (an active check, with a "checked Ns ago" note), on both platforms.
- Size cap: default 512 MiB, raise up to 2 GiB (enforced on both ends). Transfers over ~5 MiB show a progress bar on the sender.
- Turn on sync: Linux — Settings → Sync, then restart Clippy; macOS — Settings → Device sync.
- On one device: Show pairing code (Linux CLI:
clippy pair). - On the other: Enter code (Linux CLI:
clippy pair <code>, orclippy pair <code> <ip>if multicast is blocked).
That's it — the macOS Device sync pane and clippy peers list paired devices,
and either side can unpair later (which clears the pairing on both).
A firewall will break this in one direction only. Delivery is sender-driven:
a peer opens a TCP connection to port 47823 on the receiving device for
every clip it copies. Outbound is what default policies allow, so a Linux box
with ufw on (Omarchy and Ubuntu ship it enabled) still delivers its own copies
and still shows every peer green — the liveness check is outbound too — while
everything the peer copies is dropped at the door. Clippy now says so itself:
clippy status, the Sync settings tab, the pairing code screen (pairing is
inbound on the code-showing device, so a firewall there blocks pairing too), the
line after pairing, the package's post-install note and the daemon's sync.log
all name the port and print the rule. A device that can't reach the other one
while pairing now says so, rather than "no device matched the code". It stops at saying it —
opening a port is yours to decide:
sudo ufw allow from 192.168.1.0/24 to any port 47823 proto tcp comment 'Clippy LAN sync'Updating from a pre-1.5.2 build? The pairing protocol changed for the SPAKE2 security fix, so existing pairings are disabled and shown as "re-pair required" — re-pair once (both devices on 1.5.2) to resume syncing.
Same portable core (history, clipboard I/O, sync) on both platforms; the panel and OS integration use each platform's native mechanisms. macOS lets an app float a window over everything and grab a global hotkey; Wayland — by design — does not, so the Linux side uses the native Wayland protocols.
| Need | Linux (Wayland) | macOS |
|---|---|---|
| Panel pinned to the screen edge | wlr-layer-shell (gtk-layer-shell) |
borderless NSPanel at pop-up-menu window level |
| Watch the clipboard | wl-paste --watch (ext-data-control) |
NSPasteboard polling |
| Global hotkey | a desktop shortcut running clippy toggle, written by Clippy into COSMIC's or Hyprland's config, or registered with KDE Plasma's kglobalaccel |
Carbon RegisterEventHotKey (⌘⇧V) |
| Menubar / tray presence | StatusNotifierItem (Ayatana AppIndicator) | NSStatusItem |
| UI toolkit | GTK 3 (PyGObject) | AppKit (PyObjC) |
| Theme | the desktop's own palette — COSMIC's theme files, Omarchy's colors.toml, else the XDG portal |
NSAppearance light/dark |
| Storage | SQLite + files under ~/.local/share/clippy |
same (shared core) |
On Linux, one binary plays several roles:
clippy daemon # tray + overlay panel + IPC server + clipboard watcher
clippy toggle # tiny client → tells the daemon to open/close (your shortcut runs this)
clippy settings # open the settings window
clippy _store # internal: wl-paste runs this on every clipboard change
The shortcut → toggle → Unix socket → daemon path is what lets a global key
open the panel without any forbidden hotkey grab. On macOS the menubar app hosts
the panel directly.
Everything stays local under ~/.local/share/clippy (Linux) / the app's data
dir (macOS):
-
history.db— SQLite history (text + rich html inline) -
images/,files/,received/,thumbs/— copied images, file payloads, files received from peers, and cached previews -
identity.key(0600) +peers.json— sync identity key and trusted devices -
copy.wav— synthesized copy sound -
tabs.json,device-id,sync.log— custom tabs, this device's stable id, and a log of sync deliveries -
debug.log— only written when diagnostics are switched on (see below)
Preferences live in settings.json (Linux: ~/.config/clippy/), edited via the
Settings window. Fixed limits/geometry are in clippy/config.py. On Linux,
./scripts/uninstall.sh --purge removes everything. Clippy keeps a one-time
backup the first time it edits COSMIC's shortcuts, and on Hyprland it confines
itself to a marked block, so removing the shortcut leaves the rest of your
config byte-identical.
Clipboard problems on Wayland are timing- and compositor-dependent, so guessing is expensive. Two things answer most questions:
clippy types # what the clipboard is offering right now, and how Clippy
# would file it — plus who owns the X11 selectionCLIPPY_DEBUG=1 clippy daemon # trace every capture, publish and release to
# ~/.local/share/clippy/debug.log(debug_log in settings.json does the same thing permanently.) A bug report
with a few lines of that trace is worth far more than a description of the
symptom.
Two things are worth knowing before reading the output:
- An empty X11 result is usually normal. The compositor exports the
selection to X11 only while an X11 window has keyboard focus, and gates reads
the same way — so an unfocused probe (including
xclipfrom a terminal) sees nothing even when the clipboard is perfectly healthy. It means "not exported yet", not "broken". - Some compositor bugs aren't Clippy's to fix. cosmic-comp corrupts clips of
256 KiB or more when proxying them from X11 to Wayland; Clippy works around it
by writing the Wayland selection itself. See
docs/cosmic-comp-clipboard-bug.mdfor the analysis and a standalone reproducer. - Which compositor you're on changes the clipboard path. cosmic-comp mirrors
the regular selection into
data-controlbut not back out, so there Clippy reaches native-Wayland apps by owning the X11 selection and letting Xwayland re-expose it. Every other compositor bridges its own selections, so Clippy writes the Wayland selection withwl-copyand uses the X11 owner only for XWayland.clippy statusprints the desktop it detected; getting this wrong is what made a clicked tile silently set nothing on Hyprland before 1.6.0.
- No auto-paste. Selecting a tile sets the clipboard; you press Ctrl/⌘+V yourself.
- Plain/rich. A restored rich clip is offered as
text/htmland as plain text simultaneously, so apps that only ask for plain targets paste correctly without you having to pick "Copy as plain text". Setalways_plain_textin Settings if you'd rather formatting were never restored. - Linux needs a compositor with
wlr-layer-shellandext-/wlr-data-control(COSMIC, Hyprland, Sway); a plain GNOME Wayland session lacks layer-shell. The panel appears on the active output. - Rich text pastes as plain text off cosmic-comp. A restored clip has to
offer
text/htmland plain text at once, andwl-copycarries one type per invocation — so on Hyprland and friends Clippy serves the plain flavour, which pastes everywhere. XWayland apps still get both. On COSMIC, where the multi-flavour X11 owner is the Wayland selection, formatting is preserved. Lifting this needs a Wayland-backend twin of thex11cliphelper. - Source-app icons are macOS-only. macOS records the frontmost app at copy time and shows its icon on each tile. Wayland deliberately denies apps any way to query the active/foreground window or its app id (a security boundary), and no desktop portal exposes it — so this can't be supported in a Wayland session. The Linux tiles show the clip's type badge instead.
- macOS builds are ad-hoc signed (no Developer ID), so Gatekeeper shows "unidentified developer" on first launch.
clippy/
cli.py subcommand dispatch (Linux)
daemon.py AppController: tray + panel + settings + IPC + retention
panel.py Linux overlay panel, tiles, context menu, plain/rich paste
settings_window.py Linux settings UI + shortcut capture
tray.py AppIndicator tray icon
mac_app.py macOS menubar app + global hotkey
mac_panel.py macOS clipboard-history panel (tiles, tabs, filter, QuickLook)
mac_settings.py macOS settings window
mac_source.py macOS per-clip source-app map (Wayland has no equivalent)
tabs.py shared custom tabs store (tabs.json) · mac_tabs.py alias
clip_types.py shared clip type classifier (label + key + icon)
capture.py read clipboard → storage (+ sound, retention)
keeper.py put the clip back when its source app closes (Linux)
clipboard.py backend dispatch (text/image/file read + write)
backends/ per-OS clipboard: wayland.py (wl-*) + mac.py (NSPasteboard)
desktops/ per-desktop shortcut + theme: cosmic.py · hyprland.py · generic.py
x11clip.py persistent X11/XWayland selection owner (multi-flavor)
richtext.py html → plain text, for clips carrying only markup
debuglog.py opt-in capture/publish/release trace (CLIPPY_DEBUG=1)
notify.py fire-and-forget desktop notifications
updates.py GitHub release check + in-app update · mac_update.py
sync.py encrypted LAN sync engine (mDNS, pairing, streamed media)
progress.py sender transfer-progress window (large media)
storage.py SQLite history (+ html column, files, time retention)
settings.py JSON preferences
theme.py desktop light/dark + palette → generated GTK CSS
sound.py synthesize + play the copy sound
setup.py autostart, icons, app entry + shortcut dispatch
ipc.py Unix-socket control channel
config.py paths & limits
packaging/ deb · arch (PKGBUILD) · appimage · macos (py2app) builders
scripts/ install/uninstall + the test suite (scripts/README.md)
docs/ screenshots · cosmic-comp-clipboard-bug.md
MIT

