breadclip/README.md

breadclip

A Wayland clipboard history manager for Hyprland. It consists of two binaries:

• breadclipd — a background daemon that watches the clipboard and persists entries to a local SQLite database.
• breadclip — a GTK4 Layer Shell popup for browsing and recalling clipboard history.

Requirements

• Rust toolchain (edition 2021)
• GTK 4.12+
• gtk4-layer-shell
• wl-clipboard (wl-paste and wl-copy must be on $PATH)
• Hyprland (or any Wayland compositor with Layer Shell support, though the panel-positioning logic is Hyprland-specific)

Build

git clone https://git.breadway.dev/breadway/breadclip
cd breadclip
cargo build --release

The compiled binaries are at target/release/breadclip and target/release/breadclipd.

Install

Copy the binaries to somewhere on your $PATH, e.g.:

cp target/release/breadclip target/release/breadclipd ~/.local/bin/

systemd user service

A unit file is provided in contrib/:

cp contrib/breadclipd.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now breadclipd

Hyprland keybind

Add the contents of contrib/hyprland.conf to your hyprland.conf:

layerrule = blur, breadclip
layerrule = ignorezero, breadclip

bind = $mainMod, V, exec, breadclip

The layerrule lines enable the frosted-glass blur effect behind the panel.

Usage

Start the daemon (or let the systemd unit handle it):

breadclipd

Open the clipboard history popup:

breadclip

Running breadclip a second time while it is open closes it (toggle behaviour).

Keyboard shortcuts

Key	Action
Up / Down	Move selection
Enter	Copy selected entry to clipboard and close
Delete	Remove selected entry from history
Ctrl+P	Pin/unpin selected entry (pinned entries survive trimming and sort to the top)
Escape	Close without copying

Clicking an entry copies it and closes the popup. Clicking outside the panel closes it.

Filtering and search

The popup has three filter chips — All, Text, Images — and a search box. The search box filters text entries by content; image entries only appear under the Images filter.

Configuration

Optional TOML config at $XDG_CONFIG_HOME/breadclip/config.toml (typically ~/.config/breadclip/config.toml). Every key has a sensible default, so the file can be omitted entirely — a copy of the full example lives in contrib/config.toml.example:

[retention]
text = 200    # max non-pinned text entries (0 = keep none)
images = 50   # max non-pinned image entries (0 = keep none)

[panel]
width = 520   # popup panel width, px

[capture]
primary = false  # also watch the middle-click primary selection

Data storage

History is stored under $XDG_DATA_HOME/breadclip/ (typically ~/.local/share/breadclip/):

Path	Contents
history.db	SQLite database of all entries
images/	PNG/JPEG files for image entries

The daemon trims the oldest non-pinned entries automatically, keeping at most retention.text text entries and retention.images image entries (defaults 200 and 50; configurable). Pinned entries are exempt from trimming and sort to the top of the popup. Entries captured from the primary (middle-click) selection — when capture.primary = true — are stored alongside regular clipboard entries with a primary badge.

Privacy

• history.db and every file under images/ are created with 0600 permissions (owner read/write only), regardless of your umask.
• breadclipd never persists clipboard content flagged as sensitive. wl-paste --watch reports copies made with wl-copy --sensitive — which also covers offers advertising the x-kde-passwordManagerHint MIME type, the convention used by KeePassXC, Bitwarden, and other password managers to mark content they own — via CLIPBOARD_STATE=sensitive, and those copies are skipped entirely and never reach the database.
• On top of that, breadclipd runs best-effort ignore rules that skip copies that look like secrets even when the app didn't flag them: one-time codes, Luhn-valid credit card numbers, private key blocks, password:-style credential lines, and well-known API token prefixes (see breadclipd/src/ignore_rules.rs). These are deliberately conservative and are a convenience, not a security boundary — the 0600/0700 permissions are the real protection.
• That said, this is still a plaintext SQLite database of everything else you copy. Anything copied by an app that doesn't set the hint (e.g. copying a password from a terminal or a non-integrated app) will be stored like any other text entry. Treat history.db as sensitive, and don't rely on it as your only safeguard.

Theming

breadclip inherits its colour palette from bread-theme. The panel renders with an 80% opaque background so Hyprland's layerrule = blur can show a frosted-glass effect behind it.