Troubleshooting

Troubleshooting

Common Issues

Aegis not showing space indicators

Cause: Yabai integration not configured.

Fix:

1. Open Aegis Settings
2. Click "Run Setup" next to "Yabai Integration"
3. Follow the prompts to run the setup script

Or run manually:

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

Space changes not updating instantly

Cause: FIFO pipe not running or yabai signals not registered.

Fix:

1. Check if the pipe exists:

   ls -la ~/.config/aegis/yabai.pipe

2. Verify signals are registered:

   yabai -m signal --list | grep aegis

3. Re-run the setup script if needed

"Yabai not found" error

Cause: Yabai is not installed or not in PATH.

Fix:

brew install koekeishiya/formulae/yabai

Scripting addition not loaded

Cause: Yabai's scripting addition (SA) requires SIP to be partially disabled.

Fix: See the Yabai wiki for SIP configuration.

Check SA status in Aegis context menu (right-click the menu bar).

Permissions issues

Cause: Aegis needs Accessibility and Automation permissions.

Fix:

1. Open System Settings > Privacy & Security > Accessibility
2. Enable Aegis
3. If Aegis doesn't appear, drag the app into the list
4. Restart Aegis

Logs

Aegis logs are stored at:

~/Library/Logs/Aegis/aegis.log

View recent logs:

tail -100 ~/Library/Logs/Aegis/aegis.log

Config Files

All Aegis configuration is stored in:

~/.config/aegis/

Contents:

• aegis-yabai-notify - Notification script for yabai events
• yabai.pipe - FIFO pipe for instant updates (created at runtime)
• yabairc-snippet.sh - Snippet to add to your .yabairc

Reset Aegis

To reset Aegis to defaults:

# Remove preferences
defaults delete com.ccmurphy.aegis

# Remove config directory
rm -rf ~/.config/aegis

# Re-run setup on next launch