Never lose a copy again

Why Build a Clipboard History?

We’ve all been there: you copied something important but lost it after copying something else. Frustrating, right? Many clipboard managers solve this, but why not create your own with Hammerspoon? With a bit of Lua scripting, you can store your last 10 clipboard entries and quickly paste any of them with a keyboard shortcut.

What is Hammerspoon?

Hammerspoon is a powerful automation tool for macOS that lets you control system behavior using Lua scripts. From custom shortcuts to app-specific actions, it’s an incredibly flexible tool for automating your macOS experience.

In this guide, we’ll walk through setting up a clipboard history script in Hammerspoon, allowing you to save, view, and paste your last 10 copied items in seconds.

Step 1: Installing Hammerspoon

First things first—if you haven’t already, let’s get Hammerspoon set up:

1. Download Hammerspoon from hammerspoon.org.

2. Drag Hammerspoon into your Applications folder and open it.

3. macOS will ask for permissions to access your input devices. Approve these so Hammerspoon can monitor your clipboard.

4. Open Hammerspoon’s console from the menu bar and select Open Config. This will open the init.lua file in your default text editor, where you’ll add your script.

Step 2: Setting Up the Clipboard History Script

Now, let’s add the clipboard history script to Hammerspoon’s configuration. This script watches your clipboard for new items, keeps a history of the last 10 items, and lets you paste from that history at any time.

1. Open your init.lua file and add the following code:

-- Clipboard History Script for Hammerspoon
clipboardHistory = {}  -- Stores the clipboard items
maxHistorySize = 10    -- Set maximum history size

-- Function to add the current clipboard item to history
function addToClipboardHistory()
    local currentClip = hs.pasteboard.getContents()
    if currentClip and (clipboardHistory[1] ~= currentClip) then
        table.insert(clipboardHistory, 1, currentClip)  -- Add to top of history
        if #clipboardHistory > maxHistorySize then
            table.remove(clipboardHistory)  -- Remove oldest if max size is exceeded
        end
    end
end

-- Function to display clipboard history and paste selected item
function showClipboardHistory()
    local choices = {}
    for i, clip in ipairs(clipboardHistory) do
        table.insert(choices, {text = clip})
    end

    -- Create a chooser dialog for selecting history items
    local chooser = hs.chooser.new(function(choice)
        if choice then
            hs.pasteboard.setContents(choice.text)  -- Set selected item to clipboard
            hs.eventtap.keyStroke({"cmd"}, "v")     -- Paste the item
        end
    end)

    chooser:choices(choices)  -- Set chooser items as clipboard history
    chooser:show()            -- Show the chooser dialog
end

-- Watch for changes in the clipboard and update history
clipboardWatcher = hs.pasteboard.watcher.new(addToClipboardHistory)
clipboardWatcher:start()

-- Hotkey to show and paste from clipboard history
hs.hotkey.bind({"cmd", "shift"}, "V", showClipboardHistory)

Step 3: Breaking Down the Code

Let’s go over what each part of the script does:

• clipboardHistory = {}: This initializes an empty table to store clipboard items, keeping up to 10 copies.

• addToClipboardHistory(): Checks if there’s new content in the clipboard and, if it’s unique, adds it to the history. When the history exceeds 10 items, it removes the oldest.

• showClipboardHistory(): Opens a list of the last 10 copied items in a chooser dialog. When you pick an item, it sets that text as the clipboard content and pastes it in the active application.

• clipboardWatcher: Watches for changes to the clipboard, running addToClipboardHistory() whenever the clipboard updates.

• hs.hotkey.bind({"cmd", "shift"}, "V", showClipboardHistory): Binds CMD+SHIFT+V to open the clipboard history, making it quick and easy to recall recent items.

Step 4: Testing Your Clipboard History

To get everything working:

1. Save your changes in init.lua.

2. Go to the Hammerspoon menu bar and select Reload Config.

3. Copy some text, open different documents or apps, and try copying multiple items.

4. Press CMD+SHIFT+V to see your clipboard history. Choose an item, and it will automatically paste into your current app!

Wrapping Up

With Hammerspoon and this simple script, you’ve now got a personal clipboard manager built right into your Mac. No more worrying about lost copy-pastes or accidentally overwriting your clipboard!

Feel free to adjust the maxHistorySize variable if you’d like to keep more than 10 items in history. Hammerspoon offers endless possibilities, so now you’re ready to explore even more customization ideas for your macOS workflow!

Happy scripting!