clippy

A clipboard manager for the terminal. It watches your clipboard, keeps a searchable history of everything you copy, and lets you re-copy, favorite, edit, or export old items. No dependencies, just the standard library. Works on macOS, Linux, and Windows.

Install

The quickest way to get a clippy command that works from any directory:

./install.sh

This copies the app into ~/.local/lib/clippy and puts a clippy launcher in ~/.local/bin. If ~/.local/bin isn't on your PATH yet, add it:

echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.zshrc

As a Python package

Installable as a normal package, either from source or from PyPI once published:

pip install .                     # from the repo
pipx install .                    # isolated, via pipx
pip install clippy-clipboard      # from PyPI (name on PyPI is clippy-clipboard)

Using it as a library:

from clippy import ClipboardManager, add, search, stats, top

add("hello world")
print(search("hello"))

Other install options

./install.sh --pip       # install via pip into a private venv
./install.sh --system    # install into /usr/local/bin (run with sudo)
./install.sh --uninstall # remove everything it installed

You can also skip installing and run from the repo:

python -m clippy

Where your history lives

History is stored in one global file, ~/.clippy_history.json, so it's the same no matter which directory you're in. If you had an older data.json lying around, it gets copied over automatically the first time you run clippy.

You can point clippy at a different file with the CLIPPY_DATA environment variable — handy for testing:

CLIPPY_DATA=/tmp/try.json clippy watch

Each entry keeps the text, a timestamp, how many times it was copied, and an optional favorite flag. History is capped at 500 items, dropping the oldest when new copies come in.

Using it

Run clippy with no arguments to open the interactive menu. Everything you copy while it's open gets added automatically.

clippy

To just log copies to the terminal instead of the menu:

clippy watch

Commands

Menu keys

j/k or arrows   move up/down
f/b or PgUp/Dn  page
g / G           jump to top / bottom
enter           copy the selected item
/               search (Enter to search, n for next match)
e               edit in $EDITOR
f               toggle favorite
F               only show favorites
d               delete the selected item
c               clear the whole history
q               quit

GUI

clippy gui opens a frameless, draggable window with a live-updating list, a search box, and a range-delete field (try 3-10 or all). Double-click an item to copy it.

It needs a Python built with tkinter:

• macOS: brew install python-tk@3.14
• Debian/Ubuntu: sudo apt install python3-tk

If you installed with pipx and clippy gui complains about tkinter, reinstall using a Python that has it:

pipx install --python /usr/bin/python3 .

Development

clippy/          the package
  core.py        history storage and helpers
  clipboard.py   cross-platform clipboard access
  cli.py         command-line interface, TUI, and GUI

Run the tests:

python -m pytest