Clipboard History Widget

A macOS menu bar clipboard history manager built with Go and DarwinKit. Track your clipboard history and easily copy previous items with a simple click.

Features

• 📋 Menu Bar Integration: Clean menu bar icon for easy access
• 🕒 Real-time Monitoring: Automatically tracks clipboard changes
• 📚 History Storage: Keeps up to 50 clipboard entries with timestamps
• 💾 Persistent Storage: Saves history to ~/.clipboard-history.json
• ⚡ Click to Copy: Simply click any menu item to copy it to clipboard
• 🧹 Easy Management: Clear history option available
• 🎯 Lightweight: Runs as an accessory app (doesn't appear in Dock)

Installation

Prerequisites

• macOS (tested on recent versions)
• Go 1.21 or later

Build from Source

1. Clone this repository:

git clone <repository-url>
cd clip

2. Install Just (command runner):

# On macOS with Homebrew
brew install just

3. Build and run:

# Build only
just build

# Build and run immediately  
just run

# Or use Go directly
go build -o clip .
./clip

Making it Launch at Startup

To have the widget start automatically when you log in:

Option 1: Using Just (Recommended)

# Install with auto-start
just install

Option 2: Manual Installation

1. Move the built binary to a permanent location:

mkdir -p ~/Applications
mv clipboard-widget ~/Applications/

2. Create a launch agent plist file:

mkdir -p ~/Library/LaunchAgents

3. Create the file ~/Library/LaunchAgents/com.user.clipboard-widget.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.user.clipboard-widget</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/YOUR_USERNAME/Applications/clipboard-widget</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

4. Replace YOUR_USERNAME with your actual username, then load the launch agent:

launchctl load ~/Library/LaunchAgents/com.user.clipboard-widget.plist

Usage

Usage

Quick Start with Just:

# Build and run immediately
just run

# Or install permanently with auto-start
just install

# View all available commands
just help

Available Just Commands:

• just build - Build the application
• just run - Build and run the application
• just install - Build and install with auto-start
• just uninstall - Remove the widget completely
• just start/stop/restart - Control the widget service
• just status - Show widget status
• just logs - View widget logs
• just clean - Clean build artifacts

Manual Usage:

1. Launch the widget: Run the clip executable
2. Access history: Click the "CB" icon in your menu bar to see clipboard history
3. Copy previous items: Simply click any item in the menu to copy it back to your clipboard
4. Clear history: Click "Clear History" to remove all stored items
5. Quit: Click "Quit" or press Cmd+Q

How it Works

• The widget monitors your system clipboard automatically
• When new content is detected, it's added to the top of the history
• Duplicate entries are moved to the top rather than creating duplicates
• History is automatically saved to ~/.clipboard-history.json
• The menu shows the 15 most recent items with timestamps
• Long text is truncated for display but the full content is preserved
• Click any menu item to instantly copy it to your clipboard

Technical Details

Project Structure:

• main.go - Core clipboard widget application
• .justfile - Modern command runner with build/install/management tasks
• install.sh - Legacy installation script
• com.user.clipboard-widget.plist - macOS launch agent template

Implementation:

• Built with DarwinKit: Go bindings for macOS Cocoa APIs
• Thread-safe: Uses mutexes for concurrent access to clipboard history
• Memory efficient: Limits history to 50 items maximum
• Persistent: Saves/loads history automatically
• Native macOS: Uses NSStatusBar and NSMenu for native integration

Privacy & Security

• All clipboard data is stored locally in ~/.clipboard-history.json
• No data is transmitted over the network
• The widget only reads clipboard content when it changes
• You can clear the history at any time

Troubleshooting

Permission Issues

If the app doesn't detect clipboard changes, you may need to grant accessibility permissions:

1. Go to System Preferences → Security & Privacy → Privacy
2. Select "Accessibility" from the left sidebar
3. Add your terminal app or the clipboard-widget binary

Build Issues

• Ensure you have Xcode command line tools installed: xcode-select --install
• Make sure you're running on macOS with a supported version of Go

License

This project is open source. Feel free to modify and distribute according to your needs.

Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest features
• Submit pull requests
• Improve documentation