Installation

Installation

Requirements

Requirement	Details
macOS	14.0+ (Sonoma or later)
Hardware	Apple Silicon Mac with notch (recommended)
Displays	Single or multiple monitors supported
Yabai	7.0+ installed and running

Permissions Required

• Accessibility - For menu bar display and window tracking
• Bluetooth - For device connection notifications (optional)
• Notifications - For startup status notifications (optional)

---

Step 1: Install Yabai

If you haven't already installed Yabai:

brew install koekeishiya/formulae/yabai

For full functionality (space management, window moving between spaces), you need to:

1. Partially disable SIP (System Integrity Protection)
2. Install the Yabai scripting addition

See the Yabai Wiki for detailed instructions.

---

Step 2: Install Aegis

Option A: Download Release

Download the latest Aegis.app.zip from Releases, unzip, and move to /Applications.

Option B: Build from Source

git clone https://github.com/CCMurphy-Dev/Aegis.git
cd Aegis
open Aegis.xcodeproj
# Press Cmd+B to build, Cmd+R to run

---

Step 3: Grant Permissions

On first launch:

1. Go to System Settings → Privacy & Security → Accessibility
2. Enable Aegis in the list
3. If Aegis doesn't appear, click the + button and add it manually

---

Step 4: Yabai Integration

Aegis communicates with Yabai via a FIFO pipe. This enables instant updates when you switch spaces or move windows.

Automatic Setup (Recommended)

On first launch, Aegis will prompt you to run the setup if integration isn't configured. Click "Run Setup" and follow the prompts.

Alternatively, run the setup script manually:

~/.config/aegis/setup-aegis-yabai.sh

The script will:

1. Create ~/.config/aegis/ directory
2. Install aegis-yabai-notify notification script
3. Register Yabai signals for real-time events
4. Optionally add integration to ~/.yabairc for persistence

Manual Setup

If you prefer manual setup, add this to your ~/.yabairc:

# AEGIS_INTEGRATION_START
# Aegis window manager integration - DO NOT EDIT THIS SECTION
AEGIS_NOTIFY="$HOME/.config/aegis/aegis-yabai-notify"
yabai -m signal --remove aegis_space_changed 2>/dev/null || true
yabai -m signal --remove aegis_space_destroyed 2>/dev/null || true
yabai -m signal --remove aegis_window_focused 2>/dev/null || true
yabai -m signal --remove aegis_window_created 2>/dev/null || true
yabai -m signal --remove aegis_window_destroyed 2>/dev/null || true
yabai -m signal --remove aegis_window_moved 2>/dev/null || true
yabai -m signal --remove aegis_application_front_switched 2>/dev/null || true
yabai -m signal --add event=space_changed action="YABAI_EVENT_TYPE=space_changed $AEGIS_NOTIFY" label=aegis_space_changed
yabai -m signal --add event=space_destroyed action="YABAI_EVENT_TYPE=space_destroyed $AEGIS_NOTIFY" label=aegis_space_destroyed
yabai -m signal --add event=window_focused action="YABAI_EVENT_TYPE=window_focused $AEGIS_NOTIFY" label=aegis_window_focused
yabai -m signal --add event=window_created action="YABAI_EVENT_TYPE=window_created $AEGIS_NOTIFY" label=aegis_window_created
yabai -m signal --add event=window_destroyed action="YABAI_EVENT_TYPE=window_destroyed $AEGIS_NOTIFY" label=aegis_window_destroyed
yabai -m signal --add event=window_moved action="YABAI_EVENT_TYPE=window_moved $AEGIS_NOTIFY" label=aegis_window_moved
yabai -m signal --add event=application_front_switched action="YABAI_EVENT_TYPE=application_front_switched $AEGIS_NOTIFY" label=aegis_application_front_switched
# AEGIS_INTEGRATION_END

---

Step 5: Scripting Addition (Optional)

For full functionality, load the Yabai scripting addition. Add to your ~/.yabairc:

# Load scripting addition (requires sudoers entry)
sudo yabai --load-sa
yabai -m signal --add event=dock_did_restart action="sudo yabai --load-sa"

See Yabai Wiki - Installing the Scripting Addition for sudoers configuration.

---

Verifying Setup

After setup, check the status in Aegis:

1. Right-click the layout button (left side of menu bar)
2. Look at the Status section:
   • Yabai: Should show version number
   • SA: Should show "Loaded"
   • Aegis: Shows Aegis version
   • Link: Should show "Active"

If SA shows "Not loaded", click it to copy the load command to your clipboard, then paste and run in Terminal.

---

Multi-Display Setup

Aegis automatically detects external monitors and creates menu bars for each display. No additional setup is required.

Configuring Multi-Monitor Mode

Open Settings → General and select your preferred mode:

Mode	Description
Auto (default)	Single display = primary only, multiple = per monitor
Primary Only	Menu bar only on main display
Per Monitor	Each display shows only its own spaces
All Show All	Every display shows all spaces

Or set via config file:

{
    "multiMonitorMode": "perMonitor"
}

Display changes are detected instantly when monitors are connected or disconnected.

---

Updating

Aegis includes automatic update checking via Sparkle. To check manually:

Settings → General → Check for Updates

Updates are signed and verified automatically.

---

Uninstalling

1. Quit Aegis
2. Delete /Applications/Aegis.app
3. Remove the integration from ~/.yabairc (the section between AEGIS_INTEGRATION_START and AEGIS_INTEGRATION_END)
4. Delete config directory: rm -rf ~/.config/aegis/
5. Delete preferences: defaults delete com.ccmurphy.aegis