clipboard-history/README.md

clipboard-history

A Raycast/vicinae-style clipboard history manager for Omarchy, built as an Omarchy shell plugin. Fuzzy search over everything (content, type, source app, date — even text inside QR codes), rich per-type previews, and full theme integration.

Highlights

• Fuzzy search over everything — fzf-style matching across content, source app, and type. The list is always newest-first; search only filters it. Query tokens:
  • type:image|link|text|files|code|json|color|email|html|number (prefix match)
  • app:firefox — fuzzy match on the source app
  • is:pinned, today, yesterday, week, <2h, >30s, <3d
• Rich previews, per type — images rendered inline, QR codes show their decoded content, colors show a swatch with hex/rgb/hsl, links show the domain, JSON is pretty-printed, file lists show paths — every preview with metadata chips (app, date, words/lines, size, paste counts)
• QR codes — copied QR images are decoded with zbarimg; the payload is shown in the list, preview, and is searchable like any text clip — and if it encodes a link, Ctrl+O (or the preview's "Open link" chip) opens it in the browser directly
• OCR search — captured images are OCR'd with tesseract, so text inside screenshots becomes fuzzy-searchable; the recognized text shows in the preview pane and as a metadata chip
• Rich capture — a wl-paste --watch daemon records every clip with mime type, byte size, source app (via hyprctl), timestamp, and image dimensions. Text, images, and file:// URI lists (file-manager copies) are supported; password-manager clips and binary payloads are skipped
• Retention control — configure how much and how long history is kept
• Pause/resume — stop recording new copies without losing your history
• Fully theme-integrated — colors, spacing, corner radius, borders, and the monospace font all come from the Omarchy shell's theme singletons; it re-themes itself on omarchy theme set

Install

omarchy plugin add https://github.com/alanfortlink/clipboard-history.git --enable

No separate dependency command is required during installation. The picker always opens; if a helper is missing, it shows the exact package command inside the window with a Run in terminal button.

Already have images in history you'd like OCR'd? One-shot backfill:

python3 scripts/backfill-ocr.py          # add --lang deu for other languages

That's the whole install — omarchy plugin add clones the repo, validates the manifest, and enables it. It replaces the built-in omarchy.clipboard (restore it later with omarchy plugin disable alanfortlink.clipboard).

File previews

Copied files show their name, type, size, modification time, and path. Image and video files show a thumbnail and resolution; videos and audio show duration, and audio also shows codec, sample rate, and channels. PDFs show a first-page thumbnail and page information. Text and code files show the first 8 KiB. Folders and other files retain basic information. Use Previous/Next to inspect multiple copied files. Details load on selection, including for existing history.

Media previews use optional ffmpeg (ffprobe included); PDF previews use optional poppler (pdfinfo and pdftoppm). Without them, basic file information still works. Preview commands have time and output limits, and media thumbnails are skipped above 40 megapixels. Missing or moved files show an error.

Dependencies

All are regular Arch packages; nothing is downloaded or run at install time. Required: wl-clipboard, jq, python3, wtype (paste into the focused window). Optional: zbar (QR decoding) and tesseract (OCR search) — without them the picker still works and shows the omarchy pkg add … command to add them. No sudo or pkexec is required by the plugin itself.

The clipboard owner is treated as untrusted. Payloads are streamed through a capped reader and dropped when they exceed 32 MiB (images) or 4 MiB (text), or take longer than 5 s to deliver; QR decoding and OCR only run on images under 40 megapixels, as read from the file header without decoding. Override with CLIPBOARD_MAX_IMAGE_BYTES, CLIPBOARD_MAX_TEXT_BYTES, and CLIPBOARD_MAX_PARSE_PIXELS in the shell's environment.

Omarchy's default Super+Ctrl+V routes to it via the clone mechanism. An existing Super+Shift+V binding targeting omarchy.clipboard routes to it too. For a custom binding, edit the live config — ~/.config/hypr/bindings.lua on Quattro (a plain bindings.conf may exist but is not sourced):

o.bind("SUPER + SHIFT + V", "Clipboard manager",
  "omarchy-shell shell toggle omarchy.clipboard")

(If your config is still legacy bindings.conf: bindd = ALT SHIFT, V, ….)

Updating: omarchy plugin update alanfortlink.clipboard · Uninstall: omarchy plugin remove alanfortlink.clipboard

Upgrading from a pre-1.0 install

If you installed an earlier build (plugin id tank.clipboard, or a symlinked checkout via install.sh), remove it, reinstall from git, and repair any direct shortcut bindings so they target Omarchy's clone-aware omarchy.clipboard id:

omarchy plugin remove tank.clipboard --yes   # or: alanfortlink.clipboard
omarchy plugin add https://github.com/alanfortlink/clipboard-history.git --enable --yes
bash ~/.config/omarchy/plugins/alanfortlink.clipboard/scripts/configure-bindings.sh
omarchy restart shell

History data is preserved. configure-bindings.sh edits bindings.lua (or bindings.conf) and leaves a timestamped .bak copy next to it; it is only ever run when you invoke it explicitly.

Keys

Key	Action
Ctrl+N / Ctrl+P (or arrows)	navigate results
Enter	copy to clipboard and paste into the focused window
Shift+Enter	copy only
Ctrl+O	open a pure link in the browser, an image in the editor, or a file externally. Text entries stay in the picker; use Return to paste them. QR images open their decoded link in the browser; the preview pane also has clickable "Open link" chips for links and QR payloads
Ctrl+Shift+C	copy the entry's text content as plain text: for images, the OCR text (or QR payload). The QR and OCR panels also have Copy chips
Tab	pin/unpin
Ctrl+=	pause/resume recording
Delete	remove entry · Shift+Delete clear all (with confirm)
Esc	clear filter, then close

Pause/resume is also scriptable — useful for automation or a custom binding:

omarchy-shell shell call alanfortlink.clipboard pause '{"paused":"toggle"}'
omarchy-shell shell call alanfortlink.clipboard isPaused

Configuration

Settings live on the plugin's entry in the plugins array of ~/.config/omarchy/shell.json and hot-reload on save:

{
  "version": 1,
  "plugins": [
    {
      "id": "alanfortlink.clipboard",
      "historyLimit": 1500,
      "maxAgeDays": 30,
      "maxRows": 200
    }
  ]
}

Key	Default	Meaning
historyLimit	1500	max entries kept in history
maxAgeDays	0 (forever)	drop entries older than N days (images get garbage-collected; pinned entries are exempt)
maxRows	200	max rows the picker shows per search
qrDecode	true	decode QR codes with zbarimg on captured images
ocr	true	OCR captured images with tesseract (skipped automatically if not installed)
ocrLang	"eng"	tesseract language(s), e.g. "deu" or "eng+deu" — install packs with omarchy pkg add tesseract-data-deu

History lives in ~/.local/state/omarchy/clipboard-history-rich.json; image blobs are content-addressed under ~/.local/state/omarchy/clipboard-images/.

How it compares

	built-in omarchy.clipboard	sspaeti's OCR fork	Clipbasket	vicinae	clipboard-history
Fuzzy search	substring	+ OCR text	✓	✓	content + app + type + date tokens (type:, app:, <2h, today)
Previews	text/image	—	—	✓	images, QR payloads, color swatches, JSON pretty-print, links, files
Metadata	basic	basic	SQLite	✓	size, source app, dims, word/line counts, pins, paste counts
OCR search	✗	✓ (forked for it)	✗	✗	✓ (ocr, searchable + preview panel)
Retention config	300 cap	limit	✓	✓	historyLimit + maxAgeDays + GC
Pause recording	✗	✗	?	✓	✓ (in-picker + IPC)
Theme-integrated shell overlay	✓	✓	✓	own	✓ (uses Omarchy's theme singletons)

Roadmap / ideas

• autoPaste mode swap: Enter = copy-only, Shift+Enter = paste (walker-style)
• OCR language auto-detect / confidence thresholds
• Small bar widget: last-copied item + paused indicator
• Snippet editing: edit a pinned entry's content in place
• Multi-select delete, export/import of history
• Optional per-app capture exclusions beyond the password-manager hint

Development

├── manifest.json      # plugin manifest (replaces omarchy.clipboard via clonedFrom)
├── Clipboard.qml      # picker overlay: search, chips, list, keys, capture watchers
├── PreviewPane.qml    # per-type preview + metadata chips
├── Store.js           # history model: dedup, pins, retention, settings parsing
├── Fuzzy.js           # query parser, fuzzy matcher, scoring, highlighting
├── Classify.js        # type detection, app names, formatting, color math
├── capture.py         # clipboard watcher → one JSON line per clip (QR + OCR)
├── paste-entry.sh     # copy + shift-insert paste into the focused window
├── open-entry.sh      # open with the right app
├── tests/             # node --test suites for the JS logic
└── scripts/           # screenshot regeneration helpers

• Run logic tests: tests/run.sh
• Validate the manifest: omarchy plugin validate <checkout-dir>
• Regenerate screenshots: scripts/take-screenshots.sh (stages demo content and captures the picker keyboard-free over IPC)
• Hot-reload after edits: omarchy-shell shell rescanPlugins

License

MIT