PaperWM.spoon

Scrollable tiling window manager via Hammerspoon

Visit WebsiteView Source
Category
Window Manager
WM Type
tiling
License
free
Open Source
Yes
Keybindings
Yes
Scripting
Yes
Last Update
2026-04-13

Features

  • Scrollable horizontal tiling grid
  • Multi-space support
  • Floating window support
  • Window movement across spaces
  • Width and height cycling
  • Customizable gaps and margins
  • Lua configuration
  • Sketchybar integration

About

PaperWM.spoon brings scrollable tiling to macOS as a Hammerspoon Spoon plugin, inspired by the GNOME PaperWM extension. Windows tile in a horizontal scrollable grid per Mission Control space, with floating window support alongside. Fully customizable in Lua with vim-style navigation and multi-space window movement.

Who It's For

PaperWM.spoon is for Hammerspoon users who want scrollable tiling on macOS, inspired by the GNOME PaperWM extension. If you already have Hammerspoon installed and want a PaperWM-style layout — windows arranged in a horizontal scrollable grid per Space, with floating window support alongside — PaperWM.spoon installs as a Spoon plugin with no additional daemon or tool required. It's the macOS implementation of the scrollable tiling paradigm for Hammerspoon users specifically.

How It Works

PaperWM.spoon implements scrollable tiling within Hammerspoon's window management API. Windows on each Mission Control Space tile in a horizontal grid; activating a window scrolls the grid to reveal it. Floating windows coexist alongside the tiled grid without breaking the layout. Windows can be moved between Spaces using keyboard shortcuts. Width and height of tiled windows can be cycled through preset sizes. Gaps and margins are configurable in Lua. Sketchybar integration lets PaperWM.spoon emit events for a status bar to display the current Space layout.

Compared to Similar Tools

Compared to Paneru (standalone Rust daemon, touchpad-scroll navigation), PaperWM.spoon requires Hammerspoon but gets the full Hammerspoon ecosystem in return — you can combine PaperWM's layout with Hammerspoon's hotkey system, screen watchers, and other Spoons. Compared to OmniWM (scrollable columns, macOS 26 only), PaperWM.spoon works on older macOS versions via Hammerspoon. For existing Hammerspoon users who want scrollable tiling, PaperWM.spoon is the most natural integration.

Requirements

Getting Started

brew install --cask hammerspoon

Then install PaperWM.spoon:

-- In ~/.hammerspoon/init.lua
hs.loadSpoon("PaperWM")
spoon.PaperWM:bindHotkeys({
  focus_left  = {{"alt"}, "h"},
  focus_right = {{"alt"}, "l"},
  swap_left   = {{"alt", "shift"}, "h"},
  swap_right  = {{"alt", "shift"}, "l"},
})
spoon.PaperWM:start()

Full installation and configuration options are at github.com/mogenson/PaperWM.spoon.

Discussion