MacOS custom break-timer in Hammerspoon

June 2024


First, get Hammerspoon. Quoted from the site:

This is a tool for powerful automation of MacOS. At its core, Hammerspoon is just a bridge between the operating system and a Lua scripting engine.

We're going to update our init.lua file in .hammerspoon directory to implement our timer. As an aside, to quickly reload the changes, can use the following keybinding:

hs.hotkey.bind({ "alt" }, "r", function()

Now, let's get started.


What exactly is a "break-timer"? For our purposes, let's say it's a timer that runs for 25 minutes and then shows up a notification with a message: "Time to take a break!" After the notification is shown for a few seconds, the screen locks automatically. That should be enough to get us started.


To do something at every x seconds interval, we can use the hs.timer.doEvery function. The function takes two arguments - time interval and function to execute:

hs.timer.doevery(60 * 25, function()
    -- Function to execute

Notice the 60 * 25 - this is the time interval for 25 min in seconds.

Next, let's show a notification. We can do that using the function:

hs.timer.doevery(60 * 25, function()"Time to take a break!")
    -- TODO: lock screen

And finally, let's lock the screen automatically 5 seconds after the notification is shown. We can do that using the hs.caffeinate module, leading to our final break-timer implementation:

hs.timer.doevery(60 * 25, function()"Time to take a break!")
	hs.timer.doafter(5, function()

And there! Make sure you stand up, walk around and actually take a break. Stay healthy!


  1. Show a menu bar icon with remaining time left

  2. Bind a hotkey to toggle the timer

A quick look at Git Hooks