Yabai — Tiling Window Manager for macOS

Introduction

Yabai is a window management utility for macOS that extends the built-in window manager with tiling support. Created by Åsmund Vikane, it was designed to bring the productivity benefits of tiling window managers from the Linux world to macOS, letting users manage windows entirely from the keyboard.

What Yabai Does

• Tiles windows automatically using binary space partitioning, stack, or float layouts
• Manages macOS Spaces and monitors with scripted window and space manipulation
• Integrates with skhd for declarative, vim-style keyboard shortcuts
• Provides a CLI (yabai -m) for querying and controlling every aspect of window state
• Supports window opacity, borders, and focus-follows-mouse behavior

Architecture Overview

Yabai injects a scripting addition into the macOS Dock process to gain access to private accessibility APIs. This allows it to move, resize, and manage windows beyond what the public macOS APIs permit. The core is written in C and communicates via a Unix domain socket, making it fast and scriptable from any language.

Self-Hosting & Configuration

• Configuration file is ~/.yabairc, a shell script executed on startup
• Layout is set with yabai -m config layout bsp for binary space partitioning
• Window gaps and padding are configured per-space with top_padding, window_gap, etc.
• Window rules use yabai -m rule --add app="Finder" manage=off to float specific apps
• The scripting addition requires partially disabling SIP for full functionality

Key Features

• Binary space partitioning layout with automatic splits and manual overrides
• Per-space layout modes: bsp, stack, or float
• Query system returns JSON for composing complex scripts and status bar integrations
• Signal hooks execute user commands on events like window_created or space_changed
• Works with any keyboard shortcut daemon, though skhd is the recommended companion

Comparison with Similar Tools

• AeroSpace — Newer i3-like macOS tiler that does not require SIP changes; lacks some advanced features
• Amethyst — Swift-based macOS tiler using accessibility APIs; simpler setup but less scriptable
• Rectangle — Basic macOS window snapping via keyboard shortcuts; no auto-tiling
• Magnet — Paid macOS snap-to-grid tool; GUI-oriented, no scripting
• Hammerspoon — Lua-based macOS automation; more general-purpose but requires writing layout logic yourself

FAQ

Q: Do I need to disable SIP to use Yabai? A: Basic features work without disabling SIP. For the full scripting addition (spaces management, window movement across spaces), you need to partially disable SIP on Apple Silicon or Intel.

Q: How does Yabai handle multiple monitors? A: Each display gets its own set of spaces. Yabai can move windows and spaces between displays using CLI commands, and spaces are independently managed per monitor.

Q: Can I use Yabai with Stage Manager? A: No. Yabai and Stage Manager conflict because both try to control window placement. Disable Stage Manager before using Yabai.

Q: Which macOS versions are supported? A: Yabai supports macOS Big Sur through Tahoe (macOS 11 through 26). Each major release is tested for compatibility.

Sources

• https://github.com/koekeishiya/yabai
• https://github.com/koekeishiya/yabai/wiki