clippy

README

Clippy

A lightweight terminal-based clipboard history manager, built with Go and the Bubble Tea TUI framework.

Features

• 📋 Automatic Clipboard Monitoring - Continuously tracks clipboard changes in real-time
• 🕒 Persistent History - Saves clipboard history to disk across sessions using SQLite
• 🎯 Duplicate Detection - Automatically filters out duplicate entries using SHA-256 hashing
• 📌 Pin Items - Pin important entries to keep them at the top of your history
• ⌨️ Keyboard Navigation - Navigate through history with vim-style keybindings
• 🔍 Full-Content Detail View - Scroll through an entry's full content with the keyboard, no mouse required
• 📱 Clean Terminal UI - Beautiful, responsive interface that fits your workflow
• 🔄 Instant Copy - Copy any historical item back to clipboard with a single keypress

Demo

Installation

Prerequisites

• MacOS
• Linux with X11 or Wayland (uses xclip or wl-clipboard)

Homebrew (macOS / Linux)

brew install bvdwalt/tap/clippy

Install from source

git clone https://github.com/bvdwalt/clippy.git
cd clippy
go build -o clippy ./cmd/clippy
sudo mv clippy /usr/local/bin/

Install dependencies (if needed)

For X11:

sudo apt install xclip  # Ubuntu/Debian
sudo dnf install xclip  # Fedora

For Wayland:

sudo apt install wl-clipboard  # Ubuntu/Debian
sudo dnf install wl-clipboard  # Fedora

Usage

Start the clipboard history manager:

just run

Keybindings

Key	Action
↑ / k	Navigate up through history
↓ / j	Navigate down through history
Enter / c	Copy selected item to clipboard
v	Open full-content detail view for selected item
p	Toggle pin on selected item
d	Delete selected item (prompts for confirmation if pinned)
/	Enter search mode
r	Refresh/clear search results
Esc	Exit search mode (when in search)
q / Ctrl+C	Quit application

Search Mode

When you press /, you'll enter search mode where you can:

• Type to filter clipboard history using fuzzy search (similar to fzf)
• Press Enter to apply the search filter
• Press Esc to cancel and return to normal view

Detail View

The table and preview pane only show a truncated snippet of each entry. Press v to open a fullscreen view of the selected entry's full, untruncated content:

• Scroll with ↑/k, ↓/j, PgUp/PgDn, or Ctrl+U/Ctrl+D — no mouse or trackpad scroll required (useful in terminal multiplexers like zellij that capture scroll for pane navigation)
• Press Enter / c to copy the full content to clipboard
• Press Esc / q to return to the table

How It Works

Clippy monitors your system clipboard every 2 seconds and automatically captures any new content. Each clipboard entry is:

1. Hashed using SHA-256 to detect duplicates
2. Timestamped for chronological organization
3. Persisted to ~/.clippy/clippy.db using SQLite
4. Displayed in a scrollable terminal interface

The application shows a preview of each clipboard entry (truncated to 60 characters) and replaces newlines with spaces for clean display.

Pinned items always sort to the top of the list. Deleting a pinned item requires confirmation.

Project Structure

clippy/
├── cmd/clippy/           # Main application entry point
│   ├── main.go           # Application entry point
│   └── main_test.go      # Main package tests
├── demo/                 # Demo application
│   └── main.go           # Demo runner
├── internal/
│   ├── db/               # Persistence layer
│   │   └── db.go         # SQLite backend
│   ├── history/          # Clipboard history management
│   │   ├── history.go    # History manager implementation
│   │   ├── types.go      # Data structures and types
│   │   └── *_test.go     # History package tests
│   ├── search/           # Fuzzy search functionality
│   │   ├── fuzzy.go      # Fuzzy search implementation
│   │   └── *_test.go     # Search package tests
│   └── ui/               # Terminal user interface
│       ├── model.go      # Bubble Tea model
│       ├── commands.go   # UI commands and messaging
│       ├── styles/       # UI styling and themes
│       │   └── theme.go  # Color themes and styling
│       ├── table/        # Table display management
│       │   └── manager.go # Table rendering and state
│       └── *_test.go     # UI package tests
├── go.mod                # Go module definition
├── go.sum                # Go module dependencies
└── README.md             # Project documentation

Dependencies

• Bubble Tea - Terminal UI framework
• Bubbles - TUI components for Bubble Tea (table, textinput, viewport)
• Lipgloss - TUI styling
• clipboard - Cross-platform clipboard access
• modernc.org/sqlite - Pure Go SQLite driver (no CGO required)

Privacy & Security

• Clipboard history is stored locally in ~/.clippy/clippy.db
• No data is transmitted over the network
• SHA-256 hashes are used only for duplicate detection, not security
• All clipboard content is stored in plain text locally

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License.

Acknowledgments

• Built with Bubble Tea by Charm
• As well as Clipboard