Table of Contents

1. SimpleClipboard (Vim plugin)
   1. Why
   2. Features
   3. Requirements
   4. Install
   5. Quick Start
   6. Configuration
   7. How it works
   8. Systemd (optional)
   9. Security and Limits
   10. Troubleshooting
   11. Notes for macOS
   12. Development
   13. License
   14. Credits

SimpleClipboard (Vim plugin)

Make copying to the system clipboard Just Work in Vim (without +clipboard). Linux and macOS supported. Not for Neovim (Vim9 scripts).

• Primary: Rust daemon over Unix socket + small client library
• Fallbacks: pbcopy/wl-copy/xsel/xclip, then OSC52
• Auto-start daemon on VimEnter; optional auto-stop on VimLeave
• Auto copy on TextYankPost
• Detailed logging to :messages or to file

Why

• Vim without +clipboard cannot reach the system clipboard.
• External commands and terminal control sequences vary across platforms.
• This plugin provides a fast, robust, consistent path via a local daemon, with smart fallbacks.

Features

• y in Normal/Visual to copy to system clipboard
• Auto copy after yank (TextYankPost)
• Works on Wayland, X11, and macOS
• OSC52 fallback (optional)
• Configurable daemon/lib paths
• Logging and diagnostics

Requirements

• Vim 8.2+ with Vim9 scripts, +job, +channel; +timers optional
• Rust toolchain (to build the daemon and client library)
• Optional fallbacks:
  • macOS: pbcopy
  • Wayland: wl-copy (requires WAYLAND_DISPLAY)
  • X11: xsel or xclip
  • OSC52: base64 command and a terminal that supports OSC52

Install

1. Install the plugin (choose one)

   • packpath: put this repo under ~/.vim/pack/whatever/start/simpleclipboard
   • vim-plug: Plug 'yourname/simpleclipboard'
   • dein: follow dein’s instructions

2. Build the Rust backend

   1. Linux (one-liner): ./install.sh This copies: target/release/libsimpleclipboard.so -> ./lib/ target/release/simpleclipboard-daemon -> ./lib/
   2. macOS:

   cargo build –release mkdir -p lib cp target/release/libsimpleclipboard.dylib lib/ cp target/release/simpleclipboard-daemon lib/

3. Ensure the plugin directory is on 'runtimepath' (so Vim can find ./lib/*)

4. Generate help tags: :helptags

Quick Start

• Default mappings:
  • Normal: y copies the unnamed register to the system clipboard
  • Visual: y copies the current selection
• Auto copy after yank: enabled by default
• Commands:
  • :SimpleCopyYank
  • :[range]SimpleCopyRange

Configuration

Set in your vimrc:

" Daemon control
let g:simpleclipboard_daemon_enabled = 1
let g:simpleclipboard_daemon_autostart = 1
let g:simpleclipboard_daemon_autostop = 0   " off by default to avoid killing shared daemon

" Auto copy on TextYankPost
let g:simpleclipboard_auto_copy = 1

" Optional: override absolute paths
let g:simpleclipboard_libpath = ''
let g:simpleclipboard_daemon_path = ''

" Mappings
let g:simpleclipboard_no_default_mappings = 0

" Debug & fallbacks
let g:simpleclipboard_debug = 0
let g:simpleclipboard_debug_to_file = 0
let g:simpleclipboard_debug_file = ''       " default: $XDG_RUNTIME_DIR/simpleclipboard.log
let g:simpleclipboard_disable_osc52 = 0

How it works

• Preferred: Vim calls a tiny Rust client library (via libcallnr) which connects to $XDG_RUNTIME_DIR/simpleclipboard.sock (falls back to /tmp) and sends the text (bincode, up to 16 MB). The daemon sets the system clipboard via arboard.
• Fallback commands: pbcopy, wl-copy, xsel, xclip (async via job_start + chansend).
• Final fallback: OSC52 control sequence sent to /dev/tty (tmux passthrough if $TMUX is set).
• Socket readiness is checked with sockconnect() when available.

Systemd (optional)

The daemon supports socket activation via listenfd.

Example user socket ~/.config/systemd/user/simpleclipboard.socket:

[Unit]
Description=SimpleClipboard user socket

[Socket]
ListenStream=%t/simpleclipboard.sock
SocketMode=0600

[Install]
WantedBy=default.target
Example user service ~/.config/systemd/user/simpleclipboard.service:

[Unit]
Description=SimpleClipboard daemon

[Service]
ExecStart=/absolute/path/to/simpleclipboard-daemon
Restart=on-failure
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=full

• Enable and start:

systemctl –user enable –now simpleclipboard.socket Set let g:simpleclipboard_daemon_autostart = 0 in Vim to avoid double-starting.

Security and Limits

• Socket file mode 0600; placed in $XDG_RUNTIME_DIR (falls back to /tmp if unset).
• One message limit: 16 MB (daemon and client). OSC52 path truncates over limit.
• OSC52 writes control sequences to /dev/tty; some terminals/tmux configs may block it.
• Auto-stop is off by default to avoid stopping a daemon shared by multiple Vim instances.

Troubleshooting

• “Daemon executable not found …”

  • Ensure simpleclipboard-daemon exists under runtimepath/lib/, or set g:simpleclipboard_daemon_path-.

• “client library not found” -Ensure libsimpleclipboard.so (Linux) or .dylib (macOS) is under runtimepath/lib/, or set g:simpleclipboard_libpath.

• Wayland/X11/macOS fallback issues:

  • Install wl-copy / xsel / xclip / pbcopy.

• OSC52:

  • Ensure base64 is available and the terminal/tmux allows OSC52.
  • Disable via g:simpleclipboard_disable_osc52=1 if it causes flicker.

• Old Vim without sockconnect():

  • We fallback to “socket file exists” check; upgrade Vim for better readiness probing.

• Logging:

  • g:simpleclipboard_debug=1
  • g:simpleclipboard_debug_to_file=1, check $XDG_RUNTIME_DIR/simpleclipboard.log.

Notes for macOS

• Build and copy libsimpleclipboard.dylib instead of .so.
• pbcopy is present by default; the daemon path still provides best latency and reliability.

Development

• Code structure:
  • autoload/simpleclipboard.vim, plugin/simpleclipboard.vim
  • src/lib.rs: client library (C ABI)
  • src/daemon.rs (binary: simpleclipboard-daemon)
• Build:
  • cargo build –release
• Test:
  • Start Vim; :messages or the log file shows detailed steps if g:simpleclipboard_debug=1.

License

See repository.

Credits

arboard, bincode, listenfd, ctrlc