clip-stack

A lightweight clipboard history manager for the command line. Track, search, and paste your clipboard history with ease.

Why

Ever copied something important, then accidentally overwritten it? clip-stack keeps a searchable history of everything you copy, so you can find and reuse past clips instantly from the terminal.

Features

• Persistent History — SQLite-backed clipboard history that survives restarts
• Quick Search — Find any past clip by keyword
• Fuzzy Paste — Copy any history item back to clipboard by ID
• Usage Stats — See which clips you use most often
• Deduplication — Automatic duplicate detection and removal
• Monitor Mode — Background daemon that captures everything you copy

Quick Start

# Install
pip install pyperclip  # the only dependency

# Make it executable
chmod +x clip-stack.py

# Start monitoring clipboard (runs in background)
./clip-stack.py --monitor

# List recent clips
./clip-stack.py

# Search history
./clip-stack.py --search "password"

# Paste a specific item back
./clip-stack.py --paste 5

# Show statistics
./clip-stack.py --stats

Installation

Option 1: Direct Run

git clone https://github.com/xuzhentao915/clip-stack.git
cd clip-stack
pip install pyperclip
chmod +x clip-stack.py
./clip-stack.py --monitor

Option 2: System-Wide Install

pip install pyperclip
sudo cp clip-stack.py /usr/local/bin/clip-stack
clip-stack --monitor

Usage

Monitor Clipboard

$ clip-stack --monitor
Monitoring clipboard... Press Ctrl+C to stop.
History saved to: ~/.clip_stack/history.db
[10:25:30] Saved: How to configure SSH keys...
[10:26:15] Saved: export API_KEY=sk-1234567890abcdef

List History

$ clip-stack
ID     When        #Paste Content
--------------------------------------------------------------------------------
42     10:26:15    0    export API_KEY=sk-1234567890abcdef
41     10:25:30    0    How to configure SSH keys on Linux servers...
40     10:15:22    3    SELECT * FROM users WHERE id = 1;
39     10:10:05    1    docker-compose -f prod.yml up -d

Search History

$ clip-stack --search "docker"
ID     When        #Paste Content
--------------------------------------------------------------------------------
39     10:10:05    1    docker-compose -f prod.yml up -d

Paste from History

$ clip-stack --paste 42
Pasted: export API_KEY=sk-1234567890abcdef

Statistics

$ clip-stack --stats
Total entries: 42
Database: ~/.clip_stack/history.db

Most pasted:
  [5x] docker-compose -f prod.yml up -d
  [3x] SELECT * FROM users WHERE id = 1;
  [2x] npm run build && npm run start

Command Reference

Flag	Description
-l, --limit N	Show N entries (default: 20)
-s, --search TEXT	Search for TEXT in history
-p, --paste ID	Paste item ID back to clipboard
-d, --delete ID	Delete item ID from history
-c, --clear	Clear all history
--stats	Show usage statistics
--monitor	Start clipboard monitoring daemon
--dedup	Remove duplicate entries
--import FILE	Import entries from text file

How It Works

┌─────────────────────────────────────────────────────────┐
│  clip-stack --monitor                                  │
│                                                         │
│  ┌──────────┐    ┌──────────────┐    ┌───────────┐   │
│  │ Clipboard │ ──▶ │  Monitor Loop │ ──▶ │  SQLite   │   │
│  │  (system) │    │  (1s poll)    │    │  DB file  │   │
│  └──────────┘    └──────────────┘    └───────────┘   │
│                                             │          │
│  ┌──────────┐    ┌──────────────┐           │          │
│  │  Paste   │ ◀── │   Lookup &   │ ◀──────────┘          │
│  │(command) │    │   Restore    │                        │
│  └──────────┘    └──────────────┘                        │
└─────────────────────────────────────────────────────────┘

Configuration

History is stored at ~/.clip_stack/history.db (SQLite). Maximum 1000 entries are kept by default (oldest are auto-deleted).

To change the limit, edit MAX_ENTRIES in clip-stack.py.

Requirements

• Python 3.8+
• pyperclip package

License

MIT © xuzhentao915