Repolode
Submit
mogenson

mogenson/PaperWM.spoon

A tiled, scrollable window manager for macOS, written as a Spoon plugin for the Hammerspoon automation app.

Open-source alternative to:MagnetRectangle

View on GitHub
Stars
1,791
Forks
87
Open issues
23
Last commit
6 days ago

What is it?

PaperWM.spoon arranges windows on macOS in a horizontal strip of columns that scrolls left and right, similar to the PaperWM extension for GNOME. New windows are tiled automatically, and each column can be resized, stacked as an accordion, or split with another window.

It runs inside Hammerspoon and is configured in Lua. Users bind hotkeys for focus, swap, resize, moving windows between Mission Control spaces, and floating windows. Options cover window gaps, external status bars and docks, per-app default widths, window filters for choosing apps and screens, and mouse or trackpad scrolling and dragging.

The project requires macOS, Hammerspoon, and the Mission Control setting that gives each display its own spaces. Its limitations include that macOS cannot move a window fully off-screen, so tiled windows that fall outside the visible area sit in a margin at the screen edge.

Key features

  • 01Scrollable horizontal strip of tiled window columns
  • 02Keyboard focus, swap, and resize actions bound through Hammerspoon hotkeys
  • 03Accordion-style stacked columns and split-screen layouts
  • 04Move windows between Mission Control spaces
  • 05Trackpad swipe and mouse drag or scroll to move windows
  • 06Configurable gaps, external bar offsets, and per-app default widths

Use cases

  • Mac users who want GNOME PaperWM-style scrollable tiling without leaving macOS
  • Developers who keep many editor and terminal windows open and want keyboard-driven layouts
  • Users with several displays or Mission Control spaces who want consistent window placement

Quick start

  1. 1

    Clone the Spoon into the Hammerspoon Spoons directory

    git clone https://github.com/mogenson/PaperWM.spoon ~/.hammerspoon/Spoons/PaperWM.spoon
  2. 2

    Adjust Mission Control settings in System Preferences as described in the README

  3. 3

    Load the Spoon and start it in your ~/.hammerspoon/init.lua

    PaperWM = hs.loadSpoon("PaperWM") PaperWM:bindHotkeys(PaperWM.default_hotkeys) PaperWM:start()

Things to know

  • Requires macOS and the Hammerspoon automation app.
  • Requires changing Mission Control settings (separate Spaces per display) before use.
  • Windows that would be tiled off-screen are placed in a margin at the screen edges, and dragging windows between spaces or screens is hard to detect.

Topics

#window-manager#tiling#macos#hammerspoon#lua#keyboard-shortcuts#productivity#osx#paperwm#tiling-window-manager

FAQ

What is PaperWM.spoon?
A tiled, scrollable window manager for macOS, written as a Spoon plugin for the Hammerspoon automation app. PaperWM.spoon arranges windows on macOS in a horizontal strip of columns that scrolls left and right, similar to the PaperWM extension for GNOME. New windows are tiled automatically, and each column can be resized, stacked as an accordion, or split with another window.
Is PaperWM.spoon free to use? What license does it have?
PaperWM.spoon is open source under the MIT license. Check the license terms before using it in commercial products.
Is PaperWM.spoon still maintained?
Actively maintained. The last commit to PaperWM.spoon was on Oct 13, 2026.
What can I use PaperWM.spoon for?
Mac users who want GNOME PaperWM-style scrollable tiling without leaving macOS Developers who keep many editor and terminal windows open and want keyboard-driven layouts Users with several displays or Mission Control spaces who want consistent window placement
How do I install PaperWM.spoon?
Clone the Spoon into the Hammerspoon Spoons directory: git clone https://github.com/mogenson/PaperWM.spoon ~/.hammerspoon/Spoons/PaperWM.spoon Adjust Mission Control settings in System Preferences as described in the README Load the Spoon and start it in your ~/.hammerspoon/init.lua: PaperWM = hs.loadSpoon("PaperWM") PaperWM:bindHotkeys(PaperWM.default_hotkeys) PaperWM:start()
Where can I get PaperWM.spoon?
The source code and installation instructions are on GitHub: https://github.com/mogenson/PaperWM.spoon

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects