# AeroSpace — i3-Like Tiling Window Manager for macOS

> AeroSpace is a tiling window manager for macOS inspired by i3. It uses its own virtual workspace emulation instead of native macOS Spaces, does not require disabling SIP, and is configured entirely via a plain text dotfile.

## Install

Save in your project root:

# AeroSpace — i3-Like Tiling Window Manager for macOS

## Quick Use
```bash
# Install via Homebrew
brew install --cask nikitabobko/tap/aerospace

# Start AeroSpace
open -a AeroSpace

# The default config is created at ~/.aerospace.toml
# Edit it to customize layouts and keybindings
```

## Introduction
AeroSpace brings the i3 tiling window manager experience to macOS without requiring users to disable System Integrity Protection. Created by Nikita Bobko, it uses virtual workspace emulation to bypass the limitations of native macOS Spaces, offering fast workspace switching and a plain-text configuration format familiar to i3 users.

## What AeroSpace Does
- Tiles windows automatically in i3-style layouts including horizontal, vertical, and accordion splits
- Emulates virtual workspaces independent of macOS Spaces for instant switching without animations
- Uses a tree-based layout model where containers can be nested and split in any direction
- Provides a CLI (`aerospace`) for scripting and integration with status bars
- Assigns apps to specific workspaces with pattern-based window rules

## Architecture Overview
AeroSpace is a native macOS application written in Swift that communicates with the Accessibility API to manage window positions. It maintains its own workspace tree data structure rather than manipulating macOS Spaces, which avoids the animation delays and API restrictions imposed by Mission Control. The CLI communicates with the running app via IPC.

## Self-Hosting & Configuration
- Configuration file lives at `~/.aerospace.toml` in TOML format
- Keybindings follow i3 syntax: `alt-h = "focus left"`, `alt-enter = "exec-and-forget open -a Terminal"`
- Layout defaults are set per-workspace with `[workspace-to-monitor-force-assignment]`
- Window rules use `[[on-window-detected]]` blocks with `app-id` or `window-title-regex-substring` matchers
- Gaps between windows are configured with `[gaps]` section for outer and inner spacing

## Key Features
- Instant workspace switching without macOS Space transition animations
- i3-compatible keybinding syntax for a familiar experience
- Tree-based layout allowing arbitrarily nested splits and container manipulation
- CLI-first design enabling status bar integration (e.g., SketchyBar) and scripting
- No SIP disabling required, unlike Yabai's scripting addition

## Comparison with Similar Tools
- **Yabai** — More mature macOS tiler with BSP layout; requires partial SIP disable for full features
- **Amethyst** — Simpler macOS tiler with predefined layouts; less configurable but zero-config start
- **i3** — The Linux tiling WM that AeroSpace emulates; native Wayland/X11 but not available on macOS
- **Hammerspoon** — Lua-based macOS automation; can build tiling but requires significant custom code
- **Rectangle** — Keyboard-driven window snapping; no auto-tiling or workspace management

## FAQ
**Q: Does AeroSpace require disabling SIP?**
A: No. AeroSpace uses only the public macOS Accessibility API and does not inject into system processes, so SIP can remain fully enabled.

**Q: How does AeroSpace differ from Yabai?**
A: AeroSpace emulates workspaces itself rather than using macOS Spaces, avoids SIP requirements, and uses i3-style TOML config. Yabai offers BSP layout and more low-level control but needs partial SIP disable.

**Q: Can I use AeroSpace with a status bar?**
A: Yes. The `aerospace` CLI outputs workspace state as JSON, which integrates with SketchyBar, or you can use the built-in `exec-on-workspace-change` callback.

**Q: Is AeroSpace stable enough for daily use?**
A: AeroSpace is in public beta and is used as a daily driver by many users. Breaking changes may occur before version 1.0, but the core functionality is reliable.

## Sources
- https://github.com/nikitabobko/AeroSpace
- https://nikitabobko.github.io/AeroSpace/guide

---
Source: https://tokrepo.com/en/workflows/asset-a35ffe5d
Author: AI Open Source