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.
• 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".

• 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 .

It can run directly from the command line or as a service. Note that you will need to grant accessibility privileges to the binary.

Installing with Homebrew

If you are using Homebrew, you can install from the formula with:

$ brew install paneru

Or by first adding the tap and then installing by name:

$ brew tap karinushka/paneru
$ brew install paneru

Installing with Nix

See nix/README.md.

Configuration

Paneru checks for configuration in following locations:

• $HOME/.paneru
• $HOME/.paneru.toml
• $XDG_CONFIG_HOME/paneru/paneru.toml

Additionally it allows overriding the location with $PANERU_CONFIG environment variable. If none of these files exists, Paneru creates $XDG_CONFIG_HOME/paneru/paneru.toml with the built-in defaults on first launch.

A Lua script ($XDG_CONFIG_HOME/paneru/init.lua, $HOME/.paneru.lua, or $PANERU_LUA) replaces the TOML rather than layering on top of it: when one exists, no paneru.toml is read, created, or watched.

You can use the following basic configuration as a starting point. For a complete guide to all available options, keybindings, and window rules, see the Configuration Guide.

# basic .paneru.toml
[options]
focus_follows_mouse = true
mouse_follows_focus = true

[bindings]
window_focus_west = "cmd - h"
window_focus_east = "cmd - l"
window_resize = "alt - r"
window_center = "alt - c"
quit = "ctrl + alt - q"

Alternatively, the embedded Lua runtime can declare the entire configuration via paneru.setup{...}, making the TOML file optional — see the Lua Scripting Guide:

-- init.lua
paneru.setup {
  options = { focus_follows_mouse = true, mouse_follows_focus = true },
  bindings = {
    ["window focus west"] = "cmd - h",
    ["window focus east"] = "cmd - l",
    ["quit"] = "ctrl + alt - q",
  },
}

Live reloading

Changes made to the active configuration file are automatically reloaded while Paneru is running. This is useful for tweaking keyboard bindings and other settings without restarting the application.

Startup session restore

Paneru saves managed window layout state to the user state directory ($XDG_STATE_HOME/paneru/state.json, usually ~/.local/state/paneru/state.json) and loads it when Paneru starts. During the startup restore window, Paneru matches reopened windows to the saved session and restores their layout placement, virtual workspace row, and display assignment where possible.

Restore is startup-only. After the configured startup grace period expires, new or unmatched windows follow the normal configuration and window-rule behavior. Saved windows that are not present are ignored by default and the restored layout is compacted around the windows that were found. The behavior is configured with [restore]; see the Session Restore section in the configuration guide.

Running as a service

$ paneru install
$ paneru start

Installing an app launcher

To start Paneru from Spotlight, Alfred, Raycast, or another application launcher, install the lightweight app wrapper:

$ paneru install-app

This creates $HOME/Applications/Paneru.app. Opening the app starts the installed Paneru launch agent and exits immediately. Remove the wrapper with:

$ paneru uninstall-app

Running in the foreground

$ paneru

Sending Commands

Paneru exposes a send-cmd subcommand that lets you control the running instance from the command line over a Mach service (com.github.karinushka.paneru). Any command that can be bound to a hotkey can also be sent programmatically:

$ paneru send-cmd <command> [args...]

Available commands

Where <direction> is one of: west, east, north, south, first, last. Window numbers are 1-based and count columns from left to right.

Examples

# Move focus one window to the right.
$ paneru send-cmd window focus east

# Swap the current window to the left.
$ paneru send-cmd window swap west

# Center and resize in one shot (two separate calls).
$ paneru send-cmd window center && paneru send-cmd window resize

# Balance all columns to the focused window's width.
$ paneru send-cmd window balance

# Cycle backward through preset widths.
$ paneru send-cmd window shrink

# Grow the focused window's height inside its stack.
$ paneru send-cmd window vertical grow

# Jump to the left-most window.
$ paneru send-cmd window focus first

# Jump to the second window from the left.
$ paneru send-cmd window focus 2

# Switch directly to virtual workspace 3.
$ paneru send-cmd window virtualnum 3

# Send the focused window to virtual workspace 3 without following it.
$ paneru send-cmd window virtualsendnum 3

Querying and Subscribing to State

Paneru also exposes structured JSON state for scripts and status bars:

$ paneru query state --json
$ paneru query virtual-workspaces --json
$ paneru query active --json
$ paneru subscribe --json

query prints a JSON snapshot and exits. subscribe --json keeps the channel open and emits line-delimited JSON events for changes that integrations usually care about, including focus changes, virtual workspace changes, window-list changes, title changes, and display changes. See QUERY_AND_SUBSCRIBE_FORMAT.md for the full payload contract.

Scripting ideas

Because send-cmd talks to the running daemon, you can drive Paneru from shell scripts, cron jobs, or other automation tools:

• Launch-and-arrange workflow. Open an application and immediately position it: open -a Safari && sleep 0.5 && paneru send-cmd window resize.
• One-key layout reset. Use paneru send-cmd window balance to make every column the same width as the focused window — great for resetting layouts after unplugging a monitor or when windows get shuffled.
• Integration with other tools. Pipe focus events from tools like Hammerspoon or skhd into paneru send-cmd for compound actions that go beyond a single hotkey.
• Multi-display orchestration. Move a window to the next display and immediately warp the mouse there:

  paneru send-cmd window nextdisplay && paneru send-cmd mouse nextdisplay
  

• Status bar integration. Use paneru query state --json to render the initial workspace labels, then keep them current with paneru subscribe --json.

Future Enhancements

• More commands for manipulating windows: finegrained size adjustments, touchpad resizing, etc.
• Deeper scriptability building on the embedded Lua runtime, which already supports full configuration (paneru.setup), event hooks (paneru.on), keybindings (paneru.bind), and state queries — see the Lua Scripting Guide.

Communication

There is a public Matrix room #paneru:matrix.org. Join and ask any questions.

Architecture Overview

For a detailed high-level overview of Paneru's internal design, data flow, and ECS patterns, please refer to the Architecture Guide.

Paneru's architecture is built around the Bevy ECS (Entity Component System), which manages the window manager's state as a collection of entities (displays, workspaces, applications, and windows) and components.

The system is decoupled into three primary layers:

1. Platform Layer (src/platform/): Directly interfaces with macOS via objc2 and Core Graphics. It runs the native Cocoa event loop and pumps OS events into a channel consumed by Bevy.
2. Management Layer (src/manager/): Defines OS-agnostic traits (WindowManagerApi, WindowApi) that abstract window manipulation. The macOS-specific implementations (WindowManagerOS, WindowOS) bridge these traits to the Accessibility and SkyLight APIs.
3. ECS Layer (src/ecs/): The "brain" of the application. Bevy systems process incoming events, handle input triggers, and manage animations.

Repository Structure

• main branch: Contains the stable, released code.
• testing branch: Used for experimental features and architectural refactors. This branch is volatile and may be force-pushed.

Tile Scrollably Elsewhere

Here are some other projects which implement a similar workflow:

• Niri: a scrollable tiling Wayland compositor.
• PaperWM: scrollable tiling on top of GNOME Shell.
• karousel: scrollable tiling on top of KDE.
• papersway: scrollable tiling on top of sway/i3.
• hyprscroller and hyprslidr: scrollable tiling on top of Hyprland.
• PaperWM.spoon: scrollable tiling for MacOS on top of HammerSpoon.
• Nehir: scrollable tiling for MacOS