Skip to content

About

Windows-style Alt+Tab window switcher for macOS as a Hammerspoon Spoon, with a native Liquid Glass panel

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

9 Commits

Folders and files

Repository files navigation

WindowSwitcher.spoon

English | 简体中文

Windows-style Alt+Tab for macOS, as a Hammerspoon Spoon. Cmd+Tab switches between windows, not apps, on a native Liquid Glass panel.

WindowSwitcher 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.

Keys

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.

Requirements

  • 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)

Install

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.spoon

Then 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.

Configuration

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).

How it works

  • init.lua does the logic. macOS reserves Cmd+Tab, so it is caught with an hs.eventtap. Windows come from hs.window.filter, sorted by most recent use, and releasing Cmd focuses the selected one.
  • glass.swift draws the panel. Hammerspoon can't create Liquid Glass itself, so this small AppKit program does it. It's compiled to glass on first start, runs in the background, and gets one JSON command per line on stdin (show, select, hide). Clicks go back to init.lua the same way, one JSON line on stdout. Thumbnails are captured by glass with ScreenCaptureKit and cached in memory; init.lua tells it which windows to capture and when (snap). It exits when Hammerspoon reloads or quits.

Development

After changing the Spoon, run ./build.sh before committing. It regenerates docs/docs.json and Spoons/WindowSwitcher.spoon.zip, which SpoonInstall downloads.

License

MIT

About

Windows-style Alt+Tab window switcher for macOS as a Hammerspoon Spoon, with a native Liquid Glass panel

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages