English | 简体中文
Windows-style Alt+Tab for macOS, as a Hammerspoon Spoon. Cmd+Tab switches between windows, not apps, on a native Liquid Glass panel.
- Two windows of the same app are separate entries, so you can jump straight to the one you want.
- Most recently used first, minimized windows last: a quick Cmd+Tab tap goes back to the previous window without showing the panel.
- The panel is a real
NSGlassEffectView(macOS 26 Liquid Glass), not an imitation. - Window thumbnails, ready the moment the panel opens (can be turned off). Pressing Cmd+Tab captures the current window, a window is also captured when it loses focus, and all windows every 5 minutes; thumbnails are kept in memory only.
- Light: the panel is drawn by a small native helper that stays running; Cmd+Tab captures only the current window.
| Key | Action |
|---|---|
| Cmd+Tab | Next window (first press selects the previously used window) |
| Cmd+Shift+Tab | Previous window |
| Release Cmd | Switch to the selected window |
| Esc | Cancel |
| Hover a window | Marks it with a fainter box (the Cmd+Tab selection doesn't move) |
| Click a window | Switch to it |
Only windows on the current Space are listed. The panel appears on the display under the mouse.
- macOS 26 or later
- Hammerspoon, with Accessibility permission
- Xcode Command Line Tools (
xcode-select --install), used to compile the panel helper - Screen Recording permission for Hammerspoon, for the thumbnails only (without it the panel shows app icons)
With SpoonInstall — add to ~/.hammerspoon/init.lua and reload:
hs.loadSpoon("SpoonInstall")
spoon.SpoonInstall.repos.WindowSwitcher = {
url = "https://github.com/ZachariahJ/WindowSwitcher.spoon",
desc = "WindowSwitcher.spoon",
branch = "main",
}
spoon.SpoonInstall:andUse("WindowSwitcher", { repo = "WindowSwitcher", start = true })With git
git clone https://github.com/ZachariahJ/WindowSwitcher.spoon ~/.hammerspoon/Spoons/WindowSwitcher.spoonThen add to ~/.hammerspoon/init.lua and reload:
hs.loadSpoon("WindowSwitcher")
spoon.WindowSwitcher:start()To update, git pull in that folder and reload.
Either way, the first start compiles the panel helper, which freezes Hammerspoon for a few seconds.
It only recompiles when glass.swift changes.
hs.loadSpoon("WindowSwitcher")
spoon.WindowSwitcher.delay = 0 -- show the panel immediately (default 0.12 s)
spoon.WindowSwitcher.preview = 0 -- app icons only, no window thumbnails (default 1)
spoon.WindowSwitcher:start()spoon.WindowSwitcher:stop() gives you the system Cmd+Tab back.
More tweaks are documented as comments in the source, with examples:
Alt+Tab instead of Cmd+Tab, arrow keys, all Spaces, hiding apps, which display the panel appears on (init.lua);
how often thumbnails refresh (init.lua); clear or tinted glass, sizes, panel position, thumbnail size (glass.swift).
init.luadoes the logic. macOS reserves Cmd+Tab, so it is caught with anhs.eventtap. Windows come fromhs.window.filter, sorted by most recent use, and releasing Cmd focuses the selected one.glass.swiftdraws the panel. Hammerspoon can't create Liquid Glass itself, so this small AppKit program does it. It's compiled toglasson first start, runs in the background, and gets one JSON command per line on stdin (show,select,hide). Clicks go back toinit.luathe same way, one JSON line on stdout. Thumbnails are captured byglasswith ScreenCaptureKit and cached in memory;init.luatells it which windows to capture and when (snap). It exits when Hammerspoon reloads or quits.
After changing the Spoon, run ./build.sh before committing. It regenerates docs/docs.json and
Spoons/WindowSwitcher.spoon.zip, which SpoonInstall downloads.
MIT
