hammerspoon
This skill should be used when automating macOS with Hammerspoon, configuring window management hotkeys, working with Spoons (plugins), writing Lua configuration in init.lua, or using the hs CLI for scripting and reloading.
- Installs
- 41
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/plinde/claude-plugins --skill hammerspoon- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads hammerspoon automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Hammerspoon macOS Automation
Hammerspoon bridges macOS and Lua scripting for powerful desktop automation.
Directory Structure
~/.hammerspoon/
├── init.lua # Main entry point (always loaded on startup)
├── Spoons/ # Plugin directory
│ └── *.spoon/ # Individual Spoon packages
│ └── init.lua # Spoon entry point
└── .gitignore
Configuration Basics
init.lua - Entry Point
Hammerspoon always loads ~/.hammerspoon/init.lua on startup:
-- Enable CLI support (required for hs command)
require("hs.ipc")
-- Load a Spoon
hs.loadSpoon("SpoonName")
-- Configure the Spoon
spoon.SpoonName:bindHotkeys({...})
Loading Spoons
-- Load and auto-init (default)
hs.loadSpoon("MySpoon")
-- Load without global namespace
local mySpoon = hs.loadSpoon("MySpoon", false)
When loaded, Spoons are accessible via spoon.SpoonName.
CLI Usage (hs command)
Prerequisite: Add require("hs.ipc") to init.lua, then reload manually once.
# Reload configuration
hs -c 'hs.reload()'
# Show alert on screen
hs -c 'hs.alert("Hello from CLI")'
# Run any Lua code
hs -c 'print(hs.host.locale.current())'
# Get focused window info
hs -c 'print(hs.window.focusedWindow():title())'
Window Management with ShiftIt
ShiftIt is a popular Spoon for window tiling.
Installation
# Download from https://github.com/peterklijn/hammerspoon-shiftit
# Extract to ~/.hammerspoon/Spoons/ShiftIt.spoon/
Configuration
require("hs.ipc")
hs.loadSpoon("ShiftIt")
spoon.ShiftIt:bindHotkeys({
-- Halves
left = { { 'ctrl', 'cmd' }, 'left' },
right = { { 'ctrl', 'cmd' }, 'right' },
up = { { 'ctrl', 'cmd' }, 'up' },
down = { { 'ctrl', 'cmd' }, 'down' },
-- Quarters
upleft = { { 'ctrl', 'cmd' }, '1' },
upright = { { 'ctrl', 'cmd' }, '2' },
botleft = { { 'ctrl', 'cmd' }, '3' },
botright = { { 'ctrl', 'cmd' }, '4' },
-- Other
maximum = { { 'ctrl', 'cmd' }, 'm' },
toggleFullScreen = { { 'ctrl', 'cmd' }, 'f' },
center = { { 'ctrl', 'cmd' }, 'c' },
nextScreen = { { 'ctrl', 'cmd' }, 'n' },
previousScreen = { { 'ctrl', 'cmd' }, 'p' },
resizeOut = { { 'ctrl', 'cmd' }, '=' },
resizeIn = { { 'ctrl', 'cmd' }, '-' },
})
Modifier Keys
| Key | Lua Name |
|---|---|
| Command | 'cmd' |
| Control | 'ctrl' |
| Option/Alt | 'alt' |
| Shift | 'shift' |
Hotkey Binding (Without Spoons)
-- Simple hotkey
hs.hotkey.bind({'cmd', 'alt'}, 'R', function()
hs.reload()
end)
-- Hotkey with message
hs.hotkey.bind({'cmd', 'shift'}, 'H', function()
hs.alert.show('Hello!')
end)
Common Modules
hs.window - Window Management
-- Get focused window
local win = hs.window.focusedWindow()
-- Move/resize
win:moveToUnit('[0,0,0.5,1]') -- Left half
win:maximize()
win:centerOnScreen()
-- Get all windows
local allWindows = hs.window.allWindows()
hs.application - App Control
-- Launch or focus app
hs.application.launchOrFocus('Safari')
-- Get running app
local app = hs.application.get('Finder')
app:activate()
hs.alert - On-screen Messages
hs.alert.show('Message')
hs.alert.show('Message', nil, nil, 3) -- 3 second duration
hs.notify - System Notifications
hs.notify.new({title='Title', informativeText='Body'}):send()
hs.caffeinate - Sleep/Wake
-- Prevent sleep
hs.caffeinate.set('displayIdle', true)
-- Watch for sleep/wake events
hs.caffeinate.watcher.new(function(event)
if event == hs.caffeinate.watcher.systemWillSleep then
print('Going to sleep')
end
end):start()
Spoons
What is a Spoon?
Self-contained Lua plugin with standard structure:
MySpoon.spoon/
└── init.lua # Required: exports a table with methods
Official Spoon Repository
SpoonInstall - Package Manager
hs.loadSpoon("SpoonInstall")
-- Install from official repo
spoon.SpoonInstall:andUse("ReloadConfiguration", {
start = true
})
-- Install from custom repo
spoon.SpoonInstall.repos.Custom = {
url = "https://github.com/user/repo",
desc = "Custom spoons",
branch = "main",
}
spoon.SpoonInstall:andUse("CustomSpoon", { repo = "Custom" })
Configuration Reloading
Manual Reload
- Click menubar icon -> "Reload Config"
- Or bind a hotkey:
hs.hotkey.bind({'cmd', 'alt', 'ctrl'}, 'R', function()
hs.reload()
end)
Auto-reload on File Change
hs.loadSpoon("ReloadConfiguration")
spoon.ReloadConfiguration:start()
Or manually:
local configWatcher = hs.pathwatcher.new(os.getenv('HOME') .. '/.hammerspoon/', function(files)
for _, file in pairs(files) do
if file:sub(-4) == '.lua' then
hs.reload()
return
end
end
end):start()
CLI Reload
hs -c 'hs.reload()'
Note: Requires require("hs.ipc") in init.lua.
Troubleshooting
IPC Not Working
error: can't access Hammerspoon message port
Fix: Add require("hs.ipc") to init.lua and reload manually via menubar.
Spoon Not Loading
- Check path:
~/.hammerspoon/Spoons/Name.spoon/init.lua - Check Lua syntax in Spoon's init.lua
- Check Hammerspoon console for errors (menubar -> Console)
Hotkey Not Working
- Check for conflicts with system shortcuts
- Verify modifier key names are lowercase strings
- Check console for binding errors
Console and Debugging
-- Print to console
print('Debug message')
-- Inspect objects
hs.inspect(someTable)
-- Open console
hs.openConsole()
Access console: Menubar icon -> Console (or Cmd+Alt+C if bound)
Best Practices
- Always use IPC - Add
require("hs.ipc")for CLI support - Use Spoons - Don't reinvent window management
- Version control - Track
~/.hammerspoon/with git - Capture variables - Objects not stored in variables get garbage collected
- Check console - First place to look for errors
References
FAQ
What does the hammerspoon skill do?
This skill should be used when automating macOS with Hammerspoon, configuring window management hotkeys, working with Spoons (plugins), writing Lua configuration in init.lua, or using the hs CLI for scripting and reloading.
How do I install hammerspoon?
Run npx skills add https://github.com/plinde/claude-plugins --skill hammerspoon in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/hammerspoon/ (personal) or .claude/skills/hammerspoon/ (project).
Which AI agents can use hammerspoon?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is hammerspoon safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains hammerspoon?
It is published by plinde in plinde/claude-plugins. It has 41 recorded installs.
More from plinde/claude-plugins
pandoc
plinde/claude-plugins
This skill should be used when converting documents between formats (Markdown, DOCX, PDF, HTML, LaTeX, etc.) using pandoc. Use for format conversion, document generation, and preparing markdown for Google Docs or other word processors.
Popular docs & writing skills
grill-with-docs
mattpocock/skills
A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
lark-markdown
open.feishu.cn
飞书 Markdown：查看、创建、上传、编辑和比较飞书中的原生 Markdown 文件。当用户要操作飞书 Markdown 文件，或比较其远端版本及本地草稿时使用。纯本地 Markdown 文件操作不触发本 skill。不负责将 Markdown 导入为飞书在线文档，也不负责文件搜索、权限、评论、移动、删除等云空间管理操作。
writing-beats
mattpocock/skills
Writing, exploit; assemble raw material into a journey of beats, grounding each term before a beat leans on it.
writing-shape
mattpocock/skills
Writing, exploit: shape raw material into an article, paragraph by paragraph.
writing-fragments
mattpocock/skills
Writing, explore: mine raw fragments, no structure yet.
writing-for-agents
mattpocock/skills
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.