Yabai: Mastering macOS Window Management

Yabai, meaning “sick” or “cool” in Japanese slang, lives up to its name. It’s a tiling window manager for macOS that transforms the way you interact with your system, offering unparalleled control and efficiency. Forget manually resizing and repositioning windows; Yabai automates this process, allowing you to focus on your work, not your window layout. This comprehensive guide dives deep into Yabai, providing a clear path from initial installation to advanced configuration, empowering you to unlock its full potential.

Part 1: Installation and Initial Setup

Before embarking on your Yabai journey, ensure your system meets the prerequisites. Yabai requires macOS 10.10 (Yosemite) or later. While it can function without SIP (System Integrity Protection) disabled, disabling it is highly recommended for optimal performance and access to all features. Disabling SIP involves booting into Recovery Mode (Command + R on startup), opening the Terminal, executing csrutil disable, and rebooting. Remember to re-enable SIP (csrutil enable) after configuring Yabai if security is a primary concern.

Installation is typically handled through the Homebrew package manager. Open your terminal and execute the following commands:

bash
brew tap koekeishiya/formulae
brew install yabai
brew services start yabai

This installs Yabai and starts it as a background service, ensuring it runs automatically on login. You’ll also need skhd, a simple hotkey daemon that works seamlessly with Yabai. Install it using:

bash
brew install skhd
brew services start skhd

Now, create a basic configuration file for skhd:

“`bash

~/.config/skhd/skhdrc

Basic window movement

alt – h : yabai -m window –focus west
alt – l : yabai -m window –focus east
alt – k : yabai -m window –focus north
alt – j : yabai -m window –focus south

Basic window swapping

alt + shift – h : yabai -m window –swap west
alt + shift – l : yabai -m window –swap east
alt + shift + k : yabai -m window –swap north
alt + shift + j : yabai -m window –swap south

Focus on spaces

alt – 1 : yabai -m space –focus 1
alt – 2 : yabai -m space –focus 2

… and so on for other spaces

Move window to space

alt + shift – 1 : yabai -m window –space 1
alt + shift – 2 : yabai -m window –space 2

… and so on for other spaces

Toggle floating mode

alt – f : yabai -m window –toggle float
“`

Save this file as ~/.config/skhd/skhdrc and reload skhd with brew services restart skhd. You can now start experimenting with the basic window movement and space switching.

Part 2: Understanding Key Concepts

Yabai operates on several core concepts crucial for understanding its functionality:

• Spaces: Similar to macOS’s virtual desktops, spaces provide separate working environments. Yabai enhances space management by allowing you to assign specific layouts and rules to each.

• Displays: Yabai recognizes and manages individual displays, allowing for customized layouts per screen.

• Windows: The fundamental unit of manipulation. Yabai controls window positioning, sizing, and layering.

• Layouts: Define how windows are arranged within a space. Common layouts include BSP (Binary Space Partitioning), stacked, and floating.

• Rules: Allow for fine-grained control over window behavior based on application name, window title, or other properties.

• Signals: Events triggered by Yabai that can be used to execute scripts or commands, enabling automation and customization.

Part 3: Exploring Layouts and Spaces

Yabai offers several layout options:

• BSP (Binary Space Partitioning): Recursively divides the screen into vertical or horizontal splits, creating a balanced and organized layout.

• Stacked: Arranges windows in a vertical stack, similar to minimizing all but the active window.

• Float: Allows windows to be freely positioned and resized, bypassing Yabai’s tiling management.

You can cycle through layouts using a simple skhd configuration:

“`bash

Cycle layouts

alt – space : yabai -m space –layout next
“`

Combining layouts with spaces allows for highly customized workflows. For instance, you could dedicate one space to a BSP layout for coding, another to a stacked layout for writing, and a third to a floating layout for design work.

Part 4: Mastering Rules and Customization

Rules provide unparalleled control over window behavior. They allow you to specify properties for individual applications, ensuring consistent window management across your workflow. Rules are defined in a YAML file (~/.config/yabai/yabairc) and can control properties like:

• manage: Whether Yabai manages the window.
• split: The split type (horizontal or vertical) for BSP layouts.
• label: A custom label for the window.
• float: Whether the window should float.
• sticky: Whether the window should persist across spaces.
• opacity: The window’s opacity.

A simple yabairc example:

yaml
rules:
- app: "Safari"
split: horizontal
- app: "iTerm2"
sticky: true
- app: "Slack"
float: on

This configuration dictates that Safari windows should use horizontal splits in BSP layouts, iTerm2 should persist across spaces, and Slack windows should always float.

Part 5: Advanced Features and Automation

Yabai offers a wealth of advanced features:

• Padding and Gaps: Customize the spacing between windows for improved aesthetics.
• Border Customization: Control the color, thickness, and style of window borders.
• Scripting and Automation: Use AppleScript or other scripting languages to interact with Yabai and automate tasks.
• Signals: Respond to Yabai events with custom scripts, enabling dynamic adjustments to your layout.

Part 6: Troubleshooting and Community Support

Encountering issues? Yabai has a vibrant and helpful community. Consult the official documentation, explore community forums, and don’t hesitate to ask for assistance. Common troubleshooting steps include:

• Restarting Yabai and skhd: brew services restart yabai skhd
• Checking the logs: log show --predicate 'process == "yabai"'
• Verifying your configuration files: Ensure your skhdrc and yabairc are correctly formatted.

Conclusion:

Yabai offers a powerful and flexible way to manage your macOS windows. While the initial setup might seem daunting, the rewards in terms of productivity and workflow efficiency are well worth the effort. This guide provides a solid foundation for understanding and utilizing Yabai’s core features. Explore its advanced functionalities, experiment with different configurations, and tailor it to your specific needs. With patience and exploration, you can transform your macOS experience and unlock a new level of control over your digital workspace. Embrace the power of Yabai and experience the true potential of tiling window management.