# Paneru: a scrollable tiling window manager that respects macOS workspaces

> A Rust window manager whose core promise is that opening a window never resizes the ones already on screen, and that the documentation admits what that costs.

**karinushka/paneru** — A sliding, tiling window manager for MacOS.

- Repository: https://github.com/karinushka/paneru
- Stars: 2,313 · Forks: 105
- Language: Rust
- License: MIT
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/karinushka-paneru

## Windows sit on an infinite strip instead of a grid

The README states the design in one line: Paneru arranges windows on an infinite strip extending to the right. The consequence, and the reason the project exists, is that opening a new window never causes existing windows to resize. Layout stability is treated as the core principle rather than a side effect.

That is a real departure from how most tiling managers behave. A conventional grid recomputes cell sizes whenever the window count changes, so adding a window makes everything smaller. A strip does not, so a window opened later simply extends the strip off to the right and you scroll to it.

Each monitor keeps its own independent strip, and the README is specific about why: without that, windows overflow onto adjacent displays. The project credits Niri as the inspiration for the scrollable tiling workflow on macOS, and PaperWM.spoon for the sliding strip concept, while the underlying macOS window management techniques come from reading yabai's source, particularly around undocumented functions.

## Virtual workspaces layered on top of native ones

Paneru does not replace macOS workspaces, it stacks on them. You get the native Spaces for broad segregation such as work and personal, with a separate window strip on each, switchable by keyboard or touchpad gesture. Dragging a window between them works.

Inside a space, virtual workspaces group windows by task. The README describes them as multiple horizontal strips, or rows, stacked within a single space, and marks the feature as experimental. A menu bar entry shows which virtual workspace is active, which is the kind of small affordance that determines whether a stacking model is usable.

There is also focus follows mouse, session restore of managed layouts and display assignments from the last saved state, and support for native macOS tabs as used by applications such as Ghostty, which Paneru manages on the strip like any other window.

The stated motivation is display size. Conventional tiling produces either one enormous maximized window or a crowd of unusable ones on a large monitor. A strip lets you keep windows at a workable width and scroll to the ones you are not using.

## The macOS workarounds are documented, not hidden

This is the section that makes the README worth reading in full, because a non-native macOS window manager runs into several OS behaviours that have to be worked around.

Accessibility access is required to move windows at all, and the README points at System Settings under Privacy and Security if the permission dialog does not appear. Displays need the separate spaces option enabled so workspaces can be managed independently.

Multiple displays are the messiest case. Paneru parks off-screen windows to the left or right, but macOS relocates a window to a different display if it moves fully off-screen, which confuses the manager. The stated solution is to arrange additional displays above or below the main one rather than beside it. There is an option, `horizontal_mouse_warp`, that makes a vertical arrangement feel horizontal. Aerospace has a documented equivalent problem and link.

Then there is the sliver trick. Because macOS forcibly relocates fully off-screen windows, Paneru keeps a thin strip of each parked window visible at the screen edge, controlled by `sliver_width` and `sliver_height`. The README is explicit that this is a workaround for an OS limitation rather than a design choice, which is the kind of honesty that makes a technical document trustworthy.

## Installation through Cargo, Homebrew or Nix

Three install paths are documented. From crates.io:

```shell
$ cargo install paneru
```

Or from source, which is the route if you want the latest commit:

```shell
$ git clone https://github.com/karinushka/paneru.git
$ cd paneru
$ cargo build --release
$ cargo install --path .
```

Or through Homebrew, either directly or by adding the tap first:

```shell
$ brew tap karinushka/paneru
$ brew install paneru
```

Nix is supported through `nix/README.md` in the repository, and the tree also carries a `flake.nix`, a `flake.lock` and an `.envrc`.

The Lua runtime detail is worth knowing before you build from source. By default the binary embeds LuaJIT compiled from source, so no system Lua or pkg-config setup is needed. If you would rather link against a Lua installed by mise, asdf or Homebrew, you disable default features and enable `lua` instead, pointing `PKG_CONFIG_PATH` at the directory holding `luajit.pc`.

It can run from the command line or as a service, and either way it needs accessibility privileges for the binary.

## Rust workspace, Lua scripting and three recent releases

The `Cargo.toml` shows a workspace with `crates/*` members and the root package as the only default member, version 0.5.1 on edition 2024 with a minimum Rust of 1.95.0. Dependencies are lean and tell you what the design is made of: `mlua` for the Lua bridge, `serde` and `serde_json`, `regex` for window rules, `futures-lite` and `async-mach-ports` for the macOS mach port event loop, plus local crates for shared types and the Lua module.

A comment in that file explains a decision that is unusual enough to be worth surfacing: Lua 5.1 and Luau are deliberately not offered. The world-access calls are async, so the interpreter has to be able to yield out of a Rust callback, and LuaJIT can do that. The same comment argues LuaJIT's tracing JIT is worth roughly an order of magnitude on the event path where handlers run, with `lua5x` features available for scripts needing semantics LuaJIT lacks.

Configuration is read from `$HOME/.paneru`, `$HOME/.paneru.toml` or `$XDG_CONFIG_HOME/paneru/paneru.toml`, overridable with `$PANERU_CONFIG`, and a default file is created on first launch if none exists. A Lua script at `$XDG_CONFIG_HOME/paneru/init.lua`, `$HOME/.paneru.lua` or `$PANERU_LUA` replaces the TOML outright rather than layering over it, in which case no TOML is read, created or watched.

The three recent releases show active work. v0.4.4 in July 2026 added a permissions onboarding dialog, a restart command, equalize widths, Fn/Globe modifier support and oversized window widths. v0.5.0 in September added Lua configuration with a Python conversion script, focus by number, menu bar customization, an app launcher and window rule copying from the menu bar. v0.5.1 two weeks later fixed an event tap starvation bug, improved native tab detection and kept virtual workspace row 0 instead of renumbering.

## Conclusion

Paneru's central idea, an infinite strip that slides rather than reflows, is a genuine alternative to the conventional grid and it works because the layout never has to renegotiate space. The price is that macOS does not want off-screen windows, so the manager has to leave slivers visible and ask you to stack your monitors vertically instead of side by side. Both are documented honestly rather than hidden. If you have used yabai you will find the README familiar in tone, and if you have used Niri you will recognise the layout. Install with Homebrew, leave the default configuration alone for a week, and only then decide whether the strip is a better way to work than the grid.

## FAQ

### What makes Paneru different from other tiling window managers?

Windows sit on an infinite strip that extends to the right instead of filling a grid, so opening a new window never resizes the ones already open. Each monitor gets its own independent strip so windows do not overflow onto adjacent displays.

### How do I install Paneru on macOS?

Through Homebrew with `brew install paneru`, through crates.io with `cargo install paneru`, or from source by cloning and running `cargo build --release`. Nix is also supported via the nix/README.md file in the repository. Either way the binary needs accessibility permissions granted in System Settings.

### Does Paneru work with multiple monitors?

Yes, with a caveat the README spells out. Since macOS relocates windows that move fully off-screen, the recommendation is to arrange additional displays above or below the main one rather than to the left or right. There is a horizontal_mouse_warp option to make a vertical arrangement feel horizontal.

### Can I configure Paneru in Lua instead of TOML?

Yes, as of version 0.5.0. A Lua script at init.lua in your config directory, .paneru.lua in your home directory, or the path in $PANERU_LUA replaces the TOML configuration entirely rather than layering on top of it. When one of these exists, no TOML file is read, created or watched.

## Sources

- [Issues](https://github.com/karinushka/paneru/issues)
- [karinushka/paneru on GitHub](https://github.com/karinushka/paneru)
- [License: MIT](https://github.com/karinushka/paneru/blob/main/LICENSE)
- [README](https://github.com/karinushka/paneru/blob/main/README.md)
- [Releases](https://github.com/karinushka/paneru/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/karinushka-paneru