pastebox

A background clipboard history tool. Watches the system clipboard for text and images, saves everything automatically, and lets you browse, restore, or delete past items from a simple terminal menu — no GUI, no tray icon, just a clean CLI.

Installation

pip install pastebox

or clone this repo and:

pip install -e .

Linux note

On Linux, clipboard access needs one small native helper installed (this is a limitation of the underlying clipboard libraries, not pastebox itself):

sudo apt install xclip
# or, on Wayland:
sudo apt install wl-clipboard

Windows and macOS need no extra setup — the required platform libraries (pywin32 on Windows, pyobjc-framework-quartz on macOS) are installed automatically as part of pip install pastebox.

Usage

pastebox

or, without installing:

python run.py

or from your own Python code:

from pastebox import box
box.run()

All three launch the same interactive menu.

First run: setup wizard

The first time you run it, you're asked three quick questions:

• Where should clipboard history be stored (default: pastebox_data)
• Max history items to keep — type a number, or leave it as unlimited (the default) to never delete old items automatically
• How often to check the clipboard, in seconds (default: 1.0)

These are saved to pastebox.config.json so you're not asked again. Delete that file (or edit it directly) to change settings later.

Main menu

1) Start watching the clipboard
2) View / restore / delete history
3) Clear all history
4) Exit

1) Start watching — runs in the foreground, checking the clipboard on your chosen interval. Every time you copy something new (text or an image), it's saved automatically and a short log line is printed. Press Ctrl+C to stop watching and return to the menu.

2) View / restore / delete history — shows your most recent items (newest first), with a short preview and timestamp for each. From there you can:

• restore an item back onto the clipboard (so you can paste it somewhere), or
• delete a single item

3) Clear all history — deletes everything (asks for confirmation first).

How images are stored

Images aren't stuffed into the history file directly — each image is saved as its own .png file inside <data_dir>/images/, and the history file just keeps a small reference (filename, dimensions, timestamp) pointing to it. This keeps the history file itself small and fast to read, no matter how many images you've copied.

Duplicate protection

If the clipboard still holds the same text you already saved (e.g. you copied the same thing twice, or the polling loop just checked again before anything changed), pastebox won't create a duplicate entry — it only saves something new when the content actually changes.

Programmatic usage (advanced)

from pastebox import config, storage, watcher

cfg = config.get_or_create_config()
hist = storage.HistoryStorage(cfg["data_dir"], max_items=cfg["max_items"])

# start watching (blocks until Ctrl+C)
watcher.watch_loop(hist, cfg["poll_interval_seconds"])

# or work with history directly
items = hist.list_items(limit=10)
hist.add_text("some text")
hist.delete_item(items[0]["id"])
hist.clear()

Notes

• This is a local, offline tool — nothing is sent anywhere. Your clipboard history stays on your machine, in the folder you chose.
• pastebox polls the clipboard on an interval rather than hooking into OS-level clipboard change events, which keeps it simple and fully cross-platform, at the cost of a small delay (your configured poll interval, 1 second by default) before a new copy is captured.
• If you copy something pastebox can't read (e.g. a clipboard format it doesn't recognize), it's skipped silently rather than crashing the watcher.