A sliding, tiling window manager for MacOS.
About
Paneru is a MacOS window manager that arranges windows on an infinite strip,
extending to the right. A core principle is that opening a new window will
never cause existing windows to resize, maintaining your layout stability.
Each monitor operates with its own independent window strip, ensuring that
windows remain confined to their respective displays and do not "overflow" onto
adjacent monitors.
https://github.com/user-attachments/assets/cbc2e820-635f-408b-923a-6cb47c44704c
(Video by @emreekici3 - https://github.com/emreekici3/dotfiles)
https://github.com/user-attachments/assets/793e7eaa-7909-4086-8380-1fb7861f8780
Why Paneru?
- Niri-like Behavior on MacOS: Inspired by the user experience of Niri,
Paneru aims to bring a similar scrollable tiling workflow to MacOS.
- Works with MacOS workspaces: You can use existing workspaces and switch
between them with keyboard or touchpad gestures - with a separate window strip
on each. Drag and dropping windows between them works as well.
- Virtual Workspaces (Experimental): Group your windows into tasks by
stacking multiple horizontal strips (rows) within a single space. Use native
macOS workspaces for broad segregation (e.g., 'Work', 'Personal') and virtual
workspaces to stay organized within each context.
- Menu bar workspace indicator: Shows the currently active virtual
workspace in the macOS menu bar.
- Copy Window Rule: A menu bar entry that puts a ready-to-paste
[windows] configuration rule for the focused window on the clipboard, so
you never have to guess an app's bundle id.
- Startup session restore: Restores managed window layouts, virtual
workspaces, and display assignments from the last saved state when Paneru
starts.
- Focus follows mouse on MacOS: Very useful for people who would like to
avoid an extra click.
- Sliding windows with touchpad: Using a touchpad is quite natural for
navigation of the window pane.
- Native macOS tabs support: Applications like Ghostty use these, so
Paneru manages them on the layout strip like other windows.
- Optimal for Large Displays: Standard tiling window managers can be
suboptimal for large displays, often resulting in either huge maximized
windows or numerous tiny, unusable windows. Paneru addresses this by
providing a more flexible and practical arrangement.
- Improved Small Display Usability: On smaller displays (like laptops),
traditional tiling can make windows too small to be productive, forcing users
to constantly maximize. Paneru's sliding strip approach aims to provide a
better experience without this compromise.
Inspiration
The fundamental architecture and window management techniques are heavily
inspired by Yabai, another excellent MacOS window manager. Studying its
source code has provided invaluable insights into managing windows on MacOS,
particularly regarding undocumented functions.
The innovative concept of managing windows on a sliding strip is directly
inspired by Niri and PaperWM.spoon.
Installation
Recommended System Options
-
Like all non-native window managers for MacOS, Paneru requires accessibility
access to move windows. Once it runs you may get a dialog window asking for
permissions. Otherwise check the setting in System Settings under "Privacy &
Security -> Accessibility" (or "Privacy & Security -> Device Control and Data
Access" on macOS 27 and later).
-
Check your System Settings for "Displays have separate spaces" option. It
should be enabled - this allows Paneru to manage the workspaces independently.
-
Multiple displays. Paneru is moving the windows off-screen, hiding them
to the left or right. If you have multiple displays, for example your laptop
open when docked to an external monitor you may experience weird behavior.
The issue is that when MacOS notices a window being moved too far off-screen
it will relocate it to a different display - which confuses Paneru! The
solution is to change the spatial arrangement of your additional display -
instead of having it to the left or right, move it above or below your main
display.
A similar situation
exists with Aerospace window manager.
An option exists (horizontal_mouse_warp) which can make a vertical
arrangement of displays "feel" horizontal.
-
Off-screen window slivers. Because macOS will forcibly relocate windows
that are moved fully off-screen, Paneru keeps a thin sliver of each
off-screen window visible at the screen edge. The sliver_width and
sliver_height options control the size of this sliver. This is a
workaround for a macOS limitation, not a design choice.
Installing from Crates.io
Paneru is built using Rust's cargo. It can be installed directly from
crates.io or if you need the latest version, by fetching the source from Github.
$ cargo install paneru
Installing from Github
$ git clone https://github.com/karinushka/paneru.git
$ cd paneru
$ cargo build --release
$ cargo install --path .
By default, Paneru builds with the embedded Lua runtime using a vendored LuaJIT compiled from source, requiring no system-wide Lua installation or pkg-config setup.
If you prefer to link against a system- or version-manager-installed Lua (e.g. via mise, asdf, or Homebrew), disable default features and pass --features lua, making sure PKG_CONFIG_PATH contains the directory with luajit.pc:
# When using mise:
$ PKG_CONFIG_PATH="$(mise where luajit)/lib/pkgconfig:$PKG_CONFIG_PATH" cargo build --release --no-default-features --features lua
# When using Homebrew:
$ cargo build --release --no-default-features --features lua
It can run directly from the command line or as a service.
Note that you will need to grant accessibility privileges to the binary.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
