Swim.spoon

Swim (Sliding Window Management) is a Hammerspoon Spoon for stacking window management. Windows overlap so that a portion of each remains visible behind the focused one, letting you glance at adjacent windows without losing context in the foreground.

Unlike side-by-side tiling, each window keeps its intended size regardless of how many are open. Layout is on-demand: nothing rearranges automatically, and all window operations (focusing, moving, resizing, and distributing) are driven by keyboard commands.

Installation

1. Download or clone this repository as Swim.spoon into ~/.hammerspoon/Spoons/.
2. Load it in your Hammerspoon config (~/.hammerspoon/init.lua):

hs.loadSpoon("Swim")
spoon.Swim:start()

Configuration

Grid

The grid divides the screen into columns and rows; each keypress moves or resizes a window by one cell. The default is 10 columns × 6 rows:

spoon.Swim.gridConfig = { x = 12, y = 8 }

Keybindings

Operation	Keybind
Focus next window	Alt-Tab
Focus previous window	Shift-Alt-Tab
Slide left / right	Cmd-Left / Right
Slide up / down	Cmd-Up / Down
Resize wider / thinner	Shift-Cmd-Right / Left
Resize taller / shorter	Shift-Cmd-Down / Up
Fill screen height	Cmd-Opt-H
Fill screen	Cmd-Opt-F
Center window	Cmd-Opt-C
Distribute windows evenly	Cmd-Opt-=
Distribute windows evenly (full width)	Shift-Cmd-Opt-=
Move to next screen	Cmd-Opt-N

Pass a mapping table to setHotkeys before start() to override defaults:

hs.loadSpoon("Swim")
spoon.Swim:setHotkeys({
    focusRight     = {{"alt"},          "tab"},
    focusLeft      = {{"alt", "shift"}, "tab"},
    slideLeft      = {{"cmd"},          "left"},
    slideRight     = {{"cmd"},          "right"},
    -- ...
})
spoon.Swim:start()

Available action keys: focusRight, focusLeft, layoutEven, layoutEvenFull, center, fillHeight, fillScreen, moveNextScreen, slideLeft, slideRight, slideUp, slideDown, resizeWider, resizeThinner, resizeTaller, resizeShorter.

License

MIT