Emulating an iTerm2 Hotkey Window in Alacritty on macOS

Having recently switched from iTerm2 to Alacritty, I needed something similar to iTerm’s Hotkey Window. Having done a bit of Googling, I came to the conclusion that this was something that wasn’t available out of the box.

So I had to resort to looking for alternative solutions. The best one I found came from this Github response which is the current solution I use and what I will be implementing in this post. The reason for fleshing out the response with a post of my own is that I hit a few stumbling blocks along the way which I can hopefully help you avoid.

Just to give you an idea of what we are going to end up with, this is how it looks for me.

A hotkey that can open and close Alacritty from anywhere. That sounds pretty close to an iTerm Hotkey Window to me. Let’s set it up.

Enter Hammerspoon

Hammerspoon is an app that enables automation for macOS and is the crux of our solution. It is what we will use to toggle Alacritty’s visibility off of the back of a global hotkey.

To install it, head to the releases page and download the latest zip file. You should then be able to unzip it and drag it into ~/Applications.

Once it is installed, if you open it, you should get a small hammer icon appear in your menu bar. It should also pop up a small preferences menu that looks like this:

If that doesn’t appear, you can click the hammer icon annd navigate to Preferences in the dropdown.

Enable accessibility for Hammerspoon

This lost me a lot of time when I was initially implementing it. You need to make sure that accessibility has been enabled for the Hammerspoon app. The preferences window even warns you about it but I somehow missed it.

You can either do this by clicking “Enable Accessibility” in the Hammerspoon Preferences window or by going to System Settings > Privacy & Security > Accessibility > Clicking the + > And navigating to the Hammerspoon app in ~/Applications. Once that is done, you should end up with this:

Make Hammerspoon a login item

This is more for convenience and is not strictly necessary but I like having Hammerspoon open when I login. This allows me to start using the hotkey without having to remember to start Hammerspoon.

If you want to do this, navigate to System Settings > General > Login Items > Click the + > And navigate to the Hammerspoon app in ~/Applications. This should leave you with something similar to the following:

If that all worked smoothly, Hammerspoon should now open itself when you login.

Hammerspoon script

Now that we have Hammerspoon ready to go, we can write a small Lua script that will listen for the hotkey and toggle Alacritty. This script will need to be created at ~/.hammerspoon/init.lua as this is where Hammerspoon reads its config from by default. Open this file in an editor and then paste in the following script:

hs.hotkey.bind({ "option" }, "space", function()
    local alacritty = hs.application.get('Alacritty')
    if (alacritty ~= nil and alacritty:isFrontmost()) then
        alacritty:hide()
    else
        hs.application.launchOrFocus("/Applications/Alacritty.app")
    end
end)

The script checks whether Alacritty is running and makes decisions based off of that. If Alacritty isn’t running, it’s launched and displayed. If it’s running but currently hidden, it’s brought into focus. If it’s already running and visible, pressing the hotkey combination will hide it.

This is exactly what we want for a Hotkey Window like experience 🎉

The only bit that you might need to modify is on the first line. I currently have my hotkey set to Option + Space but you will need to adjust this to whatever suits you. For more information on bind(), you can look at its signature.

Getting Alacritty maximised

To finish off, I like to have my Alacritty maximised when it comes into focus so that it fills the screen without decoration. To do this, we need to create or adjust our Alacritty config file. This file lives at ~/.config/alacritty/alacritty.toml. Once you have created or navigated to this file, open it up in an editor and paste in the following:

[window]

startup_mode = "Maximized"
decorations = "None"

Save the file and then that should be it! Press your hotkey and a full screen Alacritty should appear. Press it again and it should disappear.

Some things to note

One thing I haven’t been able to solve is that Alacritty still appears in the application list when you Cmd + Tab which is functionality I use a lot. This is slightly different to iTerm where it’s possible to disable this. There are a few potential solutions out there but none of them really take my fancy. If you do find a non invasive solution that works for you, I’d love to know.

Finally, I only use one screen. No monitors or spaces. This means I haven’t tested this across different setups. You might have to adjust this so that it fits your setup but you should at least have a foundation to work from.

And that’s all I’ve got.