This is my Hammerspoon configuration file.
This file is written in literate programming style using org-mode. See init.lua for the generated file. You can see this in a nicer format on my blog post My Hammerspoon Configuration, With Commentary.
If you want to learn more about Hammerspoon, check out my book Learning Hammerspoon!
- General variables and configuration
- Spoon Management
- BetterTouchTool integration (experimental)
- URL dispatching to site-specific browsers
- Window and screen manipulation
- Organization and Productivity
- System and UI
- Other applications
- Seal application launcher/controller
- Network transitions
- Pop-up translation
- Leanpub integration
- Showing application keybindings
- Loading private configuration
- End-of-config animation
Global log level. Per-spoon log level can be configured in each Install:andUse block below.
hs.logger.defaultLogLevel="info"I use hyper, shift_hyper and ctrl_cmd as the modifiers for most of my key bindings, so I define them as variables here for easier use.
hyper = {"cmd","alt","ctrl"}
shift_hyper = {"cmd","alt","ctrl","shift"}
ctrl_cmd = {"cmd","ctrl"}Set up an abbreviation for hs.drawing.color.x11 since I use it repeatedly later on.
col = hs.drawing.color.x11Work’s logo, which I use in some of my Seal shortcuts later on.
work_logo = hs.image.imageFromPath(hs.configdir .. "/files/work_logo_2x.png")Set up SpoonInstall - this is the only spoon that needs to be manually installed (it is already there if you check out this repository), all the others are installed and configured automatically.
hs.loadSpoon("SpoonInstall")Configuration of my personal spoon repository, which contains Spoons that have not been merged in the main repo. See the descriptions at https://zzamboni.github.io/zzSpoons/.
spoon.SpoonInstall.repos.zzspoons = {
url = "https://github.com/zzamboni/zzSpoons",
desc = "zzamboni's spoon repository",
}I prefer sync notifications, makes them easier to read.
spoon.SpoonInstall.use_syncinstall = trueThis is just a shortcut to make the declarations below look more readable, i.e. Install:andUse instead of spoon.SpoonInstall:andUse.
Install=spoon.SpoonInstallI’m currently working on a new BetterTouchTool.spoon which provides integration with the BetterTouchTool AppleScript API. This is in heavy development! See the configuration for the Hammer spoon in System and UI for an example of how to use it.
-- Install:andUse("BetterTouchTool", { loglevel = 'debug' })
-- BTT = spoon.BetterTouchToolThe URLDispatcher spoon makes it possible to open URLs with different browsers. I have created different site-specific browsers using Epichrome, which allows me to keep site-specific bookmarks, search settings, etc. I also use Edge as my work browser (since it integrated with my work account), while using Brave for everything else. I also use the url_redir_decoders parameter to rewrite some URLs before they are opened, both to redirect certain URLs directly to their corresponding applications (instead of going through the web browser) and to fix a bug I have experienced in opening URLs from PDF documents using Preview.
The URLDispatcher spoon requires application IDs, which may change from time to time (e.g. in a recent Epichrome update all its apps changed IDs, which broke the dispatching until I figured it out), so I define a function which gets the path of the application and returns its ID.
function appID(app)
return hs.application.infoForBundlePath(app)['CFBundleIdentifier']
endchromeBrowser = appID('/Applications/Google Chrome.app')
edgeBrowser = appID('/Applications/Microsoft Edge.app')
braveBrowser = appID('/Applications/Brave Browser Dev.app')
DefaultBrowser = braveBrowser
WorkBrowser = edgeBrowser
JiraApp = appID('~/Applications/Epichrome SSBs/Jira.app')
WikiApp = appID('~/Applications/Epichrome SSBs/Wiki.app')
OpsGenieApp = WorkBrowser
Install:andUse("URLDispatcher",
{
config = {
url_patterns = {
{ "https?://jira%.work%.com", JiraApp },
{ "https?://wiki%.work%.com", WikiApp },
{ "https?://app.*%.opsgenie%.com", OpsGenieApp },
{ "msteams:", "com.microsoft.teams" },
{ "https?://.*%.work%.com", WorkBrowser }
},
url_redir_decoders = {
-- Send MS Teams URLs directly to the app
{ "MS Teams URLs",
"(https://teams.microsoft.com.*)", "msteams:%1", true },
-- Preview incorrectly encodes the anchor
-- character in URLs as %23, we fix it
{ "Fix broken Preview anchor URLs",
"%%23", "#", false, "Preview" },
},
default_handler = DefaultBrowser
},
start = true,
-- Enable debug logging if you get unexpected behavior
-- loglevel = 'debug'
}
)The WindowHalfsAndThirds spoon sets up multiple key bindings for manipulating the size and position of windows. This was one of the first spoons I wrote, and I still use it for window resizing.
Install:andUse("WindowHalfsAndThirds",
{
config = {
use_frame_correctness = true
},
hotkeys = 'default',
-- loglevel = 'debug'
}
)The WindowGrid spoon sets up a key binding (Hyper-g here) to overlay a grid that allows resizing windows by specifying their opposite corners.
myGrid = { w = 6, h = 4 }
Install:andUse("WindowGrid",
{
config = { gridGeometries =
{ { myGrid.w .."x" .. myGrid.h } } },
hotkeys = {show_grid = {hyper, "g"}},
start = true
}
)The WindowScreenLeftAndRight spoon sets up key bindings for moving windows between multiple screens.
Install:andUse("WindowScreenLeftAndRight",
{
config = {
animationDuration = 0
},
hotkeys = 'default',
-- loglevel = 'debug'
}
)The ToggleScreenRotation spoon sets up a key binding to rotate the external screen (the spoon can set up keys for multiple screens if needed, but by default it rotates the first external screen).
Install:andUse("ToggleScreenRotation",
{
hotkeys = { first = {hyper, "f15"} }
}
)The UniversalArchive spoon sets up a single key binding (Ctrl-Cmd-a) to archive the current item in Evernote, Mail and Outlook.
Install:andUse("UniversalArchive",
{
config = {
evernote_archive_notebook = ".Archive",
archive_notifications = false,
outlook_archive_folder = "Archive ([email protected])"
},
hotkeys = { archive = { { "ctrl", "cmd" }, "a" } }
}
)Note: I no longer use OmniFocus so the Spoon below is diabled, but this section is still here as an example.
The SendToOmniFocus spoon sets up a single key binding (Hyper-t) to send the current item to OmniFocus from multiple applications. We use the fn attribute of Install:andUse to call a function which registers some of the Epichrome site-specific-browsers I use, so that the Spoon knows how to collect items from them.
function chrome_item(n)
return { apptype = "chromeapp", itemname = n }
endfunction OF_register_additional_apps(s)
s:registerApplication("Collab", chrome_item("tab"))
s:registerApplication("Wiki", chrome_item("wiki page"))
s:registerApplication("Jira", chrome_item("issue"))
s:registerApplication("Brave Browser Dev", chrome_item("page"))
endInstall:andUse("SendToOmniFocus",
{
disable = true,
config = {
quickentrydialog = false,
notifications = false
},
hotkeys = {
send_to_omnifocus = { hyper, "t" }
},
fn = OF_register_additional_apps,
}
)I now use Org-mode for task tracking and capturing. The following snippet runs the ~/.emacs.d/bin/org-capture script to bring up an Emacs window which allows me to capture things from anywhere in the system. The code is a bit convoluted because it needs to capture the current window and restore it after the org-capture window closes, otherwise Emacs is brought to the front.
org_capture_path = os.getenv("HOME").."/.hammerspoon/files/org-capture.lua"
script_file = io.open(org_capture_path, "w")
script_file:write([[local win = hs.window.frontmostWindow()
local o,s,t,r = hs.execute("~/.emacs.d/bin/org-capture", true)
if not s then
print("Error when running org-capture: "..o.."\n")
end
win:focus()
]])
script_file:close()
hs.hotkey.bindSpec({hyper, "t"},
function ()
hs.task.new("/bin/bash", nil, { "-l", "-c", "/usr/local/bin/hs "..org_capture_path }):start()
end
)The EvernoteOpenAndTag spoon sets up some missing key bindings for note manipulation in Evernote. I no longer use Evernote for GTD, so I have it disabled for now.
Install:andUse("EvernoteOpenAndTag",
{
disable = true,
hotkeys = {
open_note = { hyper, "o" },
["open_and_tag-+work"] = { hyper, "w" },
["open_and_tag-+personal"] = { hyper, "p" },
["tag-@zzdone"] = { hyper, "z" }
}
}
)The TextClipboardHistory spoon implements a clipboard history, only for text items. It is invoked with Cmd-Shift-v.
Note: This is disabled for the moment as I experiment with BetterTouchTool’s built-in clipboard history, which I have bound to the same key combination for consistency in my workflow.
Install:andUse("TextClipboardHistory",
{
disable = true,
config = {
show_in_menubar = false,
},
hotkeys = {
toggle_clipboard = { { "cmd", "shift" }, "v" } },
start = true,
}
)The BTT_restart_Hammerspoon function sets up a BetterTouchTool widget which also executes the config_reload action from the spoon. This gets assigned to the fn config parameter in the configuration of the Hammer spoon below, which has the effect of calling the function with the Spoon object as its parameter.
This is still manual - the uuid parameter contains the ID of the BTT widget to configure, and for now you have to get it by hand from BTT and paste it here.
function BTT_restart_hammerspoon(s)
BTT:bindSpoonActions(s, {
config_reload = {
kind = 'touchbarButton',
uuid = "FF8DA717-737F-4C42-BF91-E8826E586FA1",
name = "Restart",
icon = hs.image.imageFromName(
hs.image.systemImageNames.ApplicationIcon),
color = hs.drawing.color.x11.orange,
}})
endThe Hammer spoon (get it? hehe) is a simple wrapper around some common Hammerspoon configuration variables. Note that this gets loaded from my personal repo, since it’s not in the official repository.
Install:andUse("Hammer",
{
repo = 'zzspoons',
config = { auto_reload_config = false },
hotkeys = {
config_reload = {hyper, "r"},
toggle_console = {hyper, "y"}
},
-- fn = BTT_restart_Hammerspoon,
start = true
}
)The Caffeine spoon allows preventing the display and the machine from sleeping. I use it frequently when playing music from my machine, to avoid having to unlock the screen whenever I want to change the music. In this case we also create a function BTT_caffeine_widget to configure the widget to both execute the corresponding function, and to set its icon according to the current state.
function BTT_caffeine_widget(s)
BTT:bindSpoonActions(s, {
toggle = {
kind = 'touchbarWidget',
uuid = '72A96332-E908-4872-A6B4-8A6ED2E3586F',
name = 'Caffeine',
widget_code = [[
do
title = " "
icon = hs.image.imageFromPath(spoon.Caffeine.spoonPath.."/caffeine-off.pdf")
if (hs.caffeinate.get('displayIdle')) then
icon = hs.image.imageFromPath(spoon.Caffeine.spoonPath.."/caffeine-on.pdf")
end
print(hs.json.encode({ text = title,
icon_data = BTT:hsimageToBTTIconData(icon) }))
end
]],
code = "spoon.Caffeine.clicked()",
widget_interval = 1,
color = hs.drawing.color.x11.black,
icon_only = true,
icon_size = hs.geometry.size(15,15),
BTTTriggerConfig = {
BTTTouchBarFreeSpaceAfterButton = 0,
BTTTouchBarItemPadding = -6,
},
}
})
endInstall:andUse("Caffeine", {
start = true,
hotkeys = {
toggle = { hyper, "1" }
},
-- fn = BTT_caffeine_widget,
})The MenubarFlag spoon colorizes the menubar according to the selected keyboard language or layout (functionality inspired by ShowyEdge). I use English, Spanish and German, so those are the colors I have defined.
Install:andUse("MenubarFlag",
{
config = {
colors = {
["U.S."] = { },
Spanish = {col.green, col.white, col.red},
["Latin American"] = {col.green, col.white, col.red},
German = {col.black, col.red, col.yellow},
}
},
start = true
}
)The MouseCircle spoon shows a circle around the mouse pointer when triggered. I have it disabled for now because I have the macOS shake-to-grow feature enabled.
Install:andUse("MouseCircle",
{
disable = true,
config = {
color = hs.drawing.color.x11.rebeccapurple
},
hotkeys = {
show = { hyper, "m" }
}
}
)One of my original bits of Hammerspoon code, now made into a spoon (although I keep it disabled, since I don’t really use it). The ColorPicker spoon shows a menu of the available color palettes, and when you select one, it draws swatches in all the colors in that palette, covering the whole screen. You can click on any of them to copy its name to the clipboard, or cmd-click to copy its RGB code.
Install:andUse("ColorPicker",
{
disable = true,
hotkeys = {
show = { hyper, "z" }
},
config = {
show_in_menubar = false,
},
start = true,
}
)I use Homebrew, and when I run brew update, I often wonder about what some of the formulas shown are (names are not always obvious). The BrewInfo spoon allows me to point at a Formula or Cask name and press Hyper-b or Hyper-c (for Casks) to have the output of the info command in a popup window, or the same key with Shift-Hyper to open the URL of the Formula/Cask.
Install:andUse("BrewInfo",
{
config = {
brew_info_style = {
textFont = "Inconsolata",
textSize = 14,
radius = 10 }
},
hotkeys = {
-- brew info
show_brew_info = {hyper, "b"},
open_brew_url = {shift_hyper, "b"},
-- brew cask info - not needed anymore, the above now do both
-- show_brew_cask_info = {shift_hyper, "c"},
-- open_brew_cask_url = {hyper, "c"},
}
}
)The KSheet spoon traverses the current application’s menus and builds a cheatsheet of the keyboard shortcuts, showing it in a nice popup window.
Install:andUse("KSheet",
{
hotkeys = {
toggle = { hyper, "/" }
}})The TimeMachineProgress spoon shows an indicator about the progress of the ongoing Time Machine backup. The indicator disappears when there is no backup going on.
Install:andUse("TimeMachineProgress",
{
start = true
}
)The TurboBoost spoon shows an indicator of the CPU’s Turbo Boost status, and allows disabling/enabling. This requires Turbo Boost Switcher to be installed.
(disabled because I ended up buying Turbo Boost Switcher Pro - it’s a great utility and offers a few great extra features for an excellent price, it deserves our support)
Install:andUse("TurboBoost",
{
disable = true,
config = {
disable_on_start = true
},
hotkeys = {
toggle = { hyper, "0" }
},
start = true,
-- loglevel = 'debug'
}
)The EjectMenu spoon automatically ejects all external disks before the system goes to sleep. I use this to avoid warnings from macOS when I close my laptop and disconnect it from my hub without explicitly unmounting my backup disk before. I disable the menubar icon, which is shown by default by the Spoon.
Install:andUse("EjectMenu", {
config = {
eject_on_lid_close = false,
eject_on_sleep = false,
show_in_menubar = true,
notify = true,
},
hotkeys = { ejectAll = { hyper, "=" } },
start = true,
-- loglevel = 'debug'
})The HeadphoneAutoPause spoon implements auto-pause/resume for iTunes, Spotify and others when the headphones are unplugged. Note that this goes unused since I started using wireless headphones.
Install:andUse("HeadphoneAutoPause",
{
start = true,
disable = true,
}
)The Seal spoon is a powerhouse. It implements a Spotlight-like launcher, but which allows for infinite configurability of what can be done or searched from the launcher window. I use Seal as my default launcher, triggered with Cmd-space, although I still keep Spotlight around under Hyper-space, mainly for its search capabilities.
We start by loading the spoon, and specifying which plugins we want.
Install:andUse("Seal",
{
hotkeys = { show = { {"alt"}, "space" } },
fn = function(s)
s:loadPlugins({"apps", "calc", "safari_bookmarks",
"screencapture", "useractions"})
s.plugins.safari_bookmarks.always_open_with_safari = false
s.plugins.useractions.actions =
{
<<useraction-definitions>>
}
s:refreshAllCommands()
end,
start = true,
}
)The useractions Seal plugin allows me to define my own shortcuts. For example, a bookmark to the Hammerspoon documentation page:
["Hammerspoon docs webpage"] = {
url = "http://hammerspoon.org/docs/",
icon = hs.image.imageFromName(hs.image.systemImageNames.ApplicationIcon),
},Or to manually trigger my work/non-work transition scripts (see below):
["Leave corpnet"] = {
fn = function()
spoon.WiFiTransitions:processTransition('foo', 'corpnet01')
end,
icon = work_logo,
},
["Arrive in corpnet"] = {
fn = function()
spoon.WiFiTransitions:processTransition('corpnet01', 'foo')
end,
icon = work_logo,
},Or to translate things using dict.leo.org:
["Translate using Leo"] = {
url = "http://dict.leo.org/englisch-deutsch/${query}",
icon = 'favicon',
keyword = "leo",
}The WiFiTransitions spoon allows triggering arbitrary actions when the SSID changes. I am interested in the change from my work network (corpnet01) to other networks, mainly because at work I need a proxy for all connections to the Internet. I have two applications which don’t handle these transitions gracefully on their own: Spotify and Adium. So I have written a couple of functions for helping them along.
The reconfigSpotifyProxy function quits Spotify, updates the proxy settings in its config file, and restarts it.
function reconfigSpotifyProxy(proxy)
local spotify = hs.appfinder.appFromName("Spotify")
local lastapp = nil
if spotify then
lastapp = hs.application.frontmostApplication()
spotify:kill()
hs.timer.usleep(40000)
end
-- I use CFEngine to reconfigure the Spotify preferences
cmd = string.format(
"/usr/local/bin/cf-agent -K -f %s/files/spotify-proxymode.cf%s",
hs.configdir, (proxy and " -DPROXY" or " -DNOPROXY"))
output, status, t, rc = hs.execute(cmd)
if spotify and lastapp then
hs.timer.doAfter(
3,
function()
if not hs.application.launchOrFocus("Spotify") then
hs.notify.show("Error launching Spotify", "", "")
end
if lastapp then
hs.timer.doAfter(0.5, hs.fnutils.partial(lastapp.activate, lastapp))
end
end)
end
endThe reconfigAdiumProxy function uses AppleScript to tell Adium about the change without having to restart it - only if Adium is already running.
function reconfigAdiumProxy(proxy)
app = hs.application.find("Adium")
if app and app:isRunning() then
local script = string.format([[
tell application "Adium"
repeat with a in accounts
if (enabled of a) is true then
set proxy enabled of a to %s
end if
end repeat
go offline
go online
end tell
]], hs.inspect(proxy))
hs.osascript.applescript(script)
end
endFunctions to stop applications that are disallowed in the work network.
function stopApp(name)
app = hs.application.get(name)
if app and app:isRunning() then
app:kill()
end
end
function forceKillProcess(name)
hs.execute("pkill " .. name)
end
function startApp(name)
hs.application.open(name)
endThe configuration for the WiFiTransitions spoon invoked these functions with the appropriate parameters.
Install:andUse("WiFiTransitions",
{
config = {
actions = {
-- { -- Test action just to see the SSID transitions
-- fn = function(_, _, prev_ssid, new_ssid)
-- hs.notify.show("SSID change",
-- string.format("From '%s' to '%s'",
-- prev_ssid, new_ssid), "")
-- end
-- },
{ -- Enable proxy config when joining corp network
to = "corpnet01",
fn = {hs.fnutils.partial(reconfigSpotifyProxy, true),
hs.fnutils.partial(reconfigAdiumProxy, true),
hs.fnutils.partial(forceKillProcess, "Dropbox"),
hs.fnutils.partial(stopApp, "Evernote"),
}
},
{ -- Disable proxy config when leaving corp network
from = "corpnet01",
fn = {hs.fnutils.partial(reconfigSpotifyProxy, false),
hs.fnutils.partial(reconfigAdiumProxy, false),
hs.fnutils.partial(startApp, "Dropbox"),
}
},
}
},
start = true,
}
)I live in Switzerland, and my German is far from perfect, so the PopupTranslateSelection spoon helps me a lot. It allows me to select some text and, with a keystroke, translate it to any of three languages using Google Translate. Super useful! Usually, Google’s auto-detect feature works fine, so the translate_to_<lang> keys are sufficient. I have some translate_<from>_<to> keys set up for certain language pairs for when this doesn’t quite work (I don’t think I’ve ever needed them).
local wm=hs.webview.windowMasks
Install:andUse("PopupTranslateSelection",
{
disable = true,
config = {
popup_style = wm.utility|wm.HUD|wm.titled|
wm.closable|wm.resizable,
},
hotkeys = {
translate_to_en = { hyper, "e" },
translate_to_de = { hyper, "d" },
translate_to_es = { hyper, "s" },
translate_de_en = { shift_hyper, "e" },
translate_en_de = { shift_hyper, "d" },
}
}
)I am now testing DeepLTranslate, based on PopupTranslateSelection but which uses the DeepL translator (this is disabled because I have the DeepL app installed, which binds its own global hotkeys).
Install:andUse("DeepLTranslate",
{
disable = true,
config = {
popup_style = wm.utility|wm.HUD|wm.titled|
wm.closable|wm.resizable,
},
hotkeys = {
translate = { hyper, "e" },
}
}
)The Leanpub spoon provides monitoring of book build jobs. You can read more about how I use this in my blog post Automating Leanpub book publishing with Hammerspoon and CircleCI.
Install:andUse("Leanpub",
{
config = {
watch_books = {
-- api_key gets set in init-local.lua like this:
-- spoon.Leanpub.api_key = "my-api-key"
{ slug = "learning-hammerspoon" },
{ slug = "learning-cfengine" },
{ slug = "emacs-org-leanpub" },
{ slug = "be-safe-on-the-internet" },
{ slug = "lit-config" },
{ slug = "zztestbook" },
{ slug = "cisspexampreparationguide" },
},
books_sync_to_dropbox = true,
},
start = true,
disable = true
})The KSheet spoon provides for showing the keybindings for the currently active application.
Install:andUse("KSheet", {
hotkeys = {
toggle = { hyper, "/" }
}
})In init-local.lua I keep experimental or private stuff (like API tokens) that I don’t want to publish in my main config. This file is not committed to any publicly accessible git repositories.
local localfile = hs.configdir .. "/init-local.lua"
if hs.fs.attributes(localfile) then
dofile(localfile)
endThe FadeLogo spoon simply shows an animation of the Hammerspoon logo to signal the end of the config load.
Install:andUse("FadeLogo",
{
config = {
default_run = 1.0,
},
start = true
}
)If you don’t want to use FadeLogo, you can have a regular notification.
-- hs.notify.show("Welcome to Hammerspoon", "Have fun!", "")