How nikitabobko/aerospace works
AeroSpace is an i3-like tiling window manager for macOS. Its principal workflow is a user or CLI client issuing a command, which the app server parses and executes against a tree of workspaces, monitors, and windows; layout and focus changes are applied through macOS accessibility APIs. Plain-text configuration, hotkeys, mouse interaction, event subscriptions, and the menu bar are significant supporting capabilities. The graph uses README statements and shown source/index references; unsampled implementation links are omitted or marked unverified.
Main entry points: server.swift Unix socket server · impl Command handlers · Window.swift Window model · TreeNode.swift Window tree
Components 22
User Interfaces
- CLI client
Sources/Cli/_main.swift - Menu bar UI
Sources/AppBundle/ui/TrayMenuModel.swift
Command Runtime
- Unix socket server
Sources/AppBundle/server.swift - Command parsing
Sources/AppBundle/command/parseCommand.swift - Command handlers
Sources/AppBundle/command/impl - Shell combinators
Sources/AppBundle/shell/Shell.swift - Output formatting
Sources/AppBundle/command/format.swift - Event subscriptions
Sources/AppBundle/subscriptions.swift
Configuration
- Config loading
Sources/AppBundle/config/ConfigFile.swift - Hotkey bindings
Sources/AppBundle/config/HotkeyBinding.swift - Config watcher
Sources/AppBundle/config/ConfigFileWatcher.swift
Window Management
- Window tree
Sources/AppBundle/tree/TreeNode.swift - Virtual workspaces
Sources/AppBundle/tree/Workspace.swift - Window model
Sources/AppBundle/tree/Window.swift - Tiling layout
Sources/AppBundle/layout/layoutRecursive.swift - Focus management
Sources/AppBundle/focus.swift - Mouse controls
Sources/AppBundle/mouse/mouse.swift
macOS Integration
- App lifecycle
Sources/AppBundle/tree/MacApp.swift - Accessibility adapter
Sources/AppBundle/util/accessibility.swift - Global observer
Sources/AppBundle/GlobalObserver.swift
Other components
- User
- macOS
Connections 23
- User → CLI client: issues commands
README.md - User → Menu bar UI: uses status menu
README.md - CLI client → Unix socket server: sends requests
Sources/Cli/_main.swift - Unix socket server → Command parsing: parses commands
Sources/AppBundle/server.swift - Unix socket server → Command handlers: runs handlers
Sources/AppBundle/server.swift - Shell combinators → Command handlers: runs commands
Sources/AppBundle/shell/Shell.swift - Command handlers → Output formatting: formats results
Sources/AppBundle/command/format.swift - Config loading → Hotkey bindings: defines mappings
- Config watcher → Config loading: reloads config
- Command handlers → Window tree: changes tree
- Virtual workspaces → Window tree: forms tree nodes
Sources/AppBundle/tree/Workspace.swift - Window model → Window tree: forms tree nodes
Sources/AppBundle/tree/Window.swift - Tiling layout → Window tree: reads tree
Sources/AppBundle/layout/layoutRecursive.swift - Tiling layout → Virtual workspaces: lays out workspaces
Sources/AppBundle/layout/layoutRecursive.swift - Tiling layout → Window model: positions windows
Sources/AppBundle/layout/layoutRecursive.swift - Focus management → Window model: focuses windows
- Mouse controls → Focus management: controls focus
- App lifecycle → Window model: manages windows
Sources/AppBundle/tree/MacApp.swift - App lifecycle → Accessibility adapter: uses accessibility
- Global observer → App lifecycle: observes apps
- Unix socket server → Event subscriptions: dispatches subscriptions
Sources/AppBundle/server.swift - macOS → Accessibility adapter: provides APIs
README.md - Menu bar UI → Virtual workspaces: shows workspace state
Sources/AppBundle/ui/TrayMenuModel.swift