homers

Terminal clipboard manager in Rust: a background daemon records clipboard text to SQLite, and a fuzzy TUI (homers history) lets you search, multi-select, and copy (or paste into tmux). This project is a port of Homie (Go); the CLI and paths use the homers name on purpose.

Requirements

• Rust 1.85+ (edition 2024).
• Unix (Linux, macOS, …) for homers start, stop, restart, and the hidden homers run daemon. On other platforms, build and use history, write, clear, etc.; process management is not implemented there yet.
• tmux 3.2+ if you use the optional popup bindings from homers tmux (display-popup).

Install

From a clone of this repository:

cargo install --path .

Or build the workspace binary:

cargo build --release
# binary: target/release/homers

There is no xclip, xsel, or wl-copy subprocess: clipboard I/O uses arboard (version pinned in Cargo.toml for predictable clipboard behavior). SQLite is linked via rusqlite with the bundled feature, so you do not need a system libsqlite3 for normal builds.

Linux build troubleshooting

If linking fails with errors about X11 or xcb, install your distribution’s X11 / XCB development packages (names vary: e.g. libxcb-shape0-dev, libxcb-xfixes0-dev on Debian/Ubuntu). Wayland-only setups sometimes need the corresponding Wayland client dev packages as well. The exact set depends on arboard’s enabled backends and your environment.

Quick start

1. Optional: create ~/.homerc (YAML). Supported keys include verbose, log_file, limit, max_size, ttl, clean_up, theme, clipboard_serve_ms (same general idea as Homie’s config). Unknown keys are ignored; at startup, homers logs a warning for each unknown key (e.g. old Homie use_xclip options).

2. Start the tracker:

   homers start
   

   This spawns homers run in the background (detached session on Unix).

3. Open history (fuzzy UI, Tab to pin rows, Enter to copy selection to the clipboard; PgUp / PgDn / Home / End move the selection):

   homers history
   

4. Paste into the current tmux pane after choosing an entry:

   homers history --paste
   

   When tmux sets HOMERS_TARGET_PANE (see below), --paste uses tmux load-buffer / paste-buffer.

Data and config layout

This differs from Homie’s ~/.homierc and homie/homie.db; do not point two programs at the same SQLite file unless you know what you are doing.

Shell and tmux integration

Print ready-to-source snippets:

homers shell   # bash: homers start + readline bindings (Ctrl-H / Ctrl-P)
homers tmux    # tmux: popups, copy-pipe to homers write

Typical usage:

source <(homers shell | tee -a "$HOME/.bashrc")
homers tmux >> "$HOME/.tmux.conf" && tmux source-file "$HOME/.tmux.conf"

The tmux popup for paste uses HOMERS_TARGET_PANE='#{pane_id}' homers history --paste (not Homie’s HOMIE_TARGET_PANE).

Security: only set HOMERS_TARGET_PANE from tmux’s #{pane_id} in trusted config. Pointing it at an arbitrary value could paste clipboard text into an unexpected tmux pane.

Commands (overview)

Global flags: --verbose, --log-file PATH.

.homerc notes

Example:

verbose: false
log_file: ~/.local/state/homers.log
limit: 20
max_size: 500
ttl: 0
clean_up: true
theme: tokyo-night
clipboard_serve_ms: 150

• theme values: catppuccin-mocha, catppuccin-latte, tokyo-night, nord, dracula.
• homers history --theme ... overrides .homerc for that run.
• clipboard_serve_ms controls how long Linux clipboard ownership is held after copy (default 150 ms). Higher values are safer for clipboard managers; lower values feel snappier.
• Cleanup behavior:
  • if ttl > 0, delete items older than ttl days.
  • else if total rows exceed max_size, prune down to newest limit rows.

Logging

Logging uses tracing with an RUST_LOG-style filter (see tracing-subscriber). By default, noisy arboard clipboard-manager warnings on X11 are capped unless you set RUST_LOG yourself.