Hammerspoon¶
Hammerspoon handles window management, a window grid on each
display, and application toggles. The configuration lives in home/.hammerspoon/.
| File | Purpose |
|---|---|
init.lua |
Loads the modules, sets the window grid per screen, starts the system watchers, binds the application hotkeys |
config.lua |
Display names, window grid sizes, and application layouts |
keys.lua |
Defines the hyper modifier |
sizeup.lua |
Window movement hotkeys (SizeUp emulation) |
display_grid.lua |
Arranges the four displays on the Studio |
logger.lua, tabletools.lua |
Logging and table helpers |
Press hyper + r to reload the configuration.
Modifiers¶
| Name | Key Combination |
|---|---|
| hyper | ctrl + opt + cmd |
| meta | cmd + shift |
Window Management¶
| Action | Key Combination |
|---|---|
| reload config | hyper + r |
| show grid | hyper + g |
| make full screen | hyper + m |
| center and 60% | hyper + c |
| move to left half | hyper + left |
| move to right half | hyper + right |
| move to top half | hyper + up |
| move to lower half | hyper + down |
| move to upper left (25%) | ctrl + opt + shift + left |
| move to upper right (25%) | ctrl + opt + shift + up |
| move to lower left (25%) | ctrl + opt + shift + down |
| move to lower right (25%) | ctrl + opt + shift + right |
| move to next monitor | ctrl + opt + right |
| move to previous monitor | ctrl + opt + left |
Window Grid¶
hyper + g shows a grid over the screen. Click or type a
cell to move the focused window there. Each display gets its grid from
config.displays.grids in config.lua, matched by the exact screen name. A
display that is not in that list gets config.displays.defaultGrid, which is
3x2.
| Screen name | Grid |
|---|---|
WQX DP (1), WQX DP (2) |
6x4 |
PM161Q B1 (1), PM161Q B1 (2) |
3x2 |
XREAL One |
3x2 |
| any other display | 3x2 (default) |
To find a screen name, press hyper + 9 and read the Hammerspoon console.
Studio Display Layout¶
The Studio has four displays in a 2x2 layout. The Air and the Mini do not use
this layout. Do not press hyper + f on them, because
display_grid.lua moves their displays to the wrong positions.
| Action | Key Combination |
|---|---|
| swap the two top displays, re-apply layout | hyper + f |
| dump display configuration | hyper + 9 |
The top row is two identical WQX DP panels. They report identical EDIDs, down to the serial number, so macOS cannot tell them apart and sometimes hands their IDs out the other way round when the displays wake from sleep. Nothing in software can tell which physical panel is on the left, so the grid keeps the tops in whatever order they are in, and hyper + f swaps them when they come back reversed.
The other slots are found on every run: PM161Q B1 is bottom-left, and
whatever display is left over, the KVM feed, is bottom-right. To re-apply the
grid without swapping, run hs -c 'fix2x2Grid()'.
Application Toggle¶
| Action | Key Combination |
|---|---|
| cmux | hyper + i |
| Discord | hyper + d |
| Slack | hyper + s |
| Telegram Desktop | hyper + t |
| Sublime Text | hyper + e |
| Tower | hyper + w |
| Zed | hyper + x |
| Messages | hyper + a |
| Vivaldi | hyper + v |
| Obsidian | hyper + o |
Utilities¶
| Action | Key Combination |
|---|---|
| window hints (current app) | hyper + . |
| battery/screen callbacks | hyper + , |
| display watcher status | hyper + 0 |