Hammerspoon Clipboard Manager: A Lua-Powered History Tool

Clipboard Management with Lua

Build a clipboard history manager in Hammerspoon with fuzzy search and paste, all driven by a few Lua scripts.

Hammerspoon bridges macOS internals to Lua. You get window management, clipboard, automation triggers, and system events — all scriptable.

By the end of this 12 min guide, you'll have a working Hammerspoon setup and practical Clipboard workflows you can use immediately.

• Understand what Hammerspoon does and why it matters for System
• Install and configure Hammerspoon for your environment
• Build Clipboard-specific workflows with real examples
• Troubleshoot common Hammerspoon issues with concrete fixes

hs.distributednotification Setup

Install Hammerspoon:

brew install --cask hammerspoon

• System environment with appropriate permissions
• No prior Clipboard experience needed
• A terminal with true color support
• Git for version-controlling your config

Storing Clipboard History

Your init.lua is the entry point. Split large configs into modules under lua/ and require them. Set hs.window.animationDuration = 0 for instant snapping.

Here's a foundational configuration to start with:

-- init.lua
hs.window.animationDuration = 0
hs.hotkey.bind({"cmd","alt"}, "left", function()
local f = hs.window.focusedWindow():frame()
local s = hs.window.focusedWindow():screen():frame()
f.x, f.y, f.w, f.h = s.x, s.y, s.w/2, s.h
hs.window.focusedWindow():setFrame(f)
end)

• Begin with this config and make small, incremental changes
• Document each setting with inline comments
• Test changes one at a time to isolate issues
• Keep your config in a Git repo for easy rollback and sharing

Search, Filter & Paste

With Hammerspoon configured, these Clipboard-specific workflows will save you time every day:

• Cmd+Alt+Arrows snap windows to halves
• Window layouts saved and restored per display config
• App switcher with a custom menu
• Clipboard history accessible from anywhere

Persistence & Privacy Settings

Once you're comfortable with Hammerspoon basics, these advanced techniques will transform your Clipboard workflow:

• Watch for WiFi/network changes with hs.wifi.watcher
• Build menu bar widgets with hs.menubar
• Auto-arrange windows when external displays connect
• Create a hyper key with Karabiner + Hammerspoon

Clipboard Watcher Bugs

Here are the most common Hammerspoon issues and how to fix them:

• Windows not moving? Check Accessibility permissions
• Config errors? Run hs.reload() or check the console
• App not found? Use hs.application.find()
• Menu bar not showing? Check hs.menubar.new() return value

Your Lua Clipboard Tool

Congratulations — you now have a solid Hammerspoon foundation. Here's where to go next:

• Explore the official Hammerspoon documentation for features not covered here
• Join the Clipboard community (GitHub Discussions, Discord, or Reddit)
• Check the related tutorials below for deeper Clipboard dives
• Build your own Hammerspoon configuration and share it with the community