Skip to content

Configuration

Jump to bottom
Christopher Murphy edited this page Feb 22, 2026 · 2 revisions

Configuration

Accessing Settings

Right-click the layout button (left side of menu bar) → Settings

Or open Settings via the context menu on any space indicator.

Settings Categories

General

Setting Description
Launch at Login Start Aegis automatically when you log in
Check for Updates Manually check for new versions
Yabai Integration View status and run setup if needed

Menu Bar

Setting Description Default
Height Menu bar height in pixels 28
Padding Horizontal padding 12
Corner Radius Rounded corners 8
Background Opacity Transparency level 0.9

Space Indicators

Setting Description Default
Circle Size Size of space number circle 20
Icon Size Size of window icons 16
Max Icons Maximum icons before overflow 4
Show Stack Badge Display count for stacked windows On

Notch HUD

Setting Description Default
Auto-hide Delay Seconds before HUD hides 1.5
Progress Bar Width Width of volume/brightness bar 120
Progress Bar Height Height of the bar 4
Show Media HUD Display Now Playing when media is playing On
Media HUD Right Panel Visualizer or Track Info display Visualizer
Media HUD Auto-hide Hide media HUD after showing track info Off

Media HUD Track Info

When Track Info mode is selected for the Media HUD right panel:

  • Song title and artist name are displayed
  • Panel expands on track change to show full text
  • Panel collapses after 3 seconds to standard width
  • Long text scrolls with a smooth marquee animation
  • Title and artist scroll independently (only if they overflow)
  • Tap album art to toggle between visualizer and track info modes

System Status

Setting Description Default
Show Battery Display battery indicator On
Show WiFi Display network indicator On
Show Clock Display time On
Show Date Display date On
Date Format Long (January 15) or Short (1/15) Short
Battery Low Level Threshold for yellow color 20%
Battery Critical Level Threshold for red color 10%
Show Focus Name Display Focus mode name Off

Animation

Setting Description Default
Spring Response Animation snappiness (lower = snappier) 0.3
Spring Damping Bounciness (higher = less bounce) 0.8
Fade Duration Opacity transition time 0.2

Behavior

Setting Description Default
Expand Context Button on Scroll Show label when scrolling context button On

When disabled, only the icon changes during scroll - saves CPU from SwiftUI re-renders.

App Switcher

Setting Description Default
Scroll Threshold Scroll distance to move selection (1-10) 3
Notched Scroll Full reset after each step (vs continuous) On

The app switcher supports multiple input methods:

  • Keyboard: Cmd+Tab / Cmd+Shift+Tab to cycle, Cmd+1-9 for direct selection
  • Mouse: Hover to highlight, click to select
  • Scroll: Two-finger scroll to cycle through windows

Multi-Display

Setting Description Default
Multi-Monitor Mode How to display menu bars across monitors Auto

Available modes:

Mode Description
Auto 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

Display changes are detected instantly via CoreGraphics callbacks when monitors are connected or disconnected.

Config File Locations

All Aegis configuration is stored in:

~/.config/aegis/

Contents

File Description
config.json JSON config file for settings (hot-reload)
CONFIG_OPTIONS.md Auto-generated documentation for all settings
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

JSON Config File

Aegis supports editing settings via a JSON config file at ~/.config/aegis/config.json. Changes are applied automatically when you save the file (hot-reload).

Features:

  • Only specify settings you want to change - defaults are used for anything not specified
  • See CONFIG_OPTIONS.md in the same directory for all available options
  • Both config file and Settings panel work together (file takes priority)

Example config.json:

{
    "_docs": "See CONFIG_OPTIONS.md for all available settings",

    "appSwitcherEnabled": true,
    "appSwitcherCmdScrollEnabled": false,

    "showDeviceHUD": true,
    "deviceHUDAutoHideDelay": 3.0,
    "excludedBluetoothDevices": ["watch"],

    "showMediaHUD": true,
    "mediaHUDRightPanelMode": "visualizer",

    "showFocusHUD": true,

    "expandContextButtonOnScroll": true,

    "maxAppIconsPerSpace": 3,
    "excludedApps": ["Finder", "Aegis"],

    "multiMonitorMode": "auto"
}

Note: Both showMediaHUD and showMusicHUD work as config keys (alias for backward compatibility).

UserDefaults

Settings are also stored in UserDefaults (macOS preferences system):

~/Library/Preferences/com.ccmurphy.aegis.plist

The JSON config file takes priority over UserDefaults when both specify the same setting.

Logs

~/Library/Logs/Aegis/aegis.log

Logs rotate automatically at 5MB.

Resetting Configuration

Reset All Settings

defaults delete com.ccmurphy.aegis

Reset Yabai Integration

rm -rf ~/.config/aegis
# Then re-run setup on next launch

Full Reset

# Remove preferences
defaults delete com.ccmurphy.aegis

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

# Remove yabairc integration (edit manually)
# Delete lines between AEGIS_INTEGRATION_START and AEGIS_INTEGRATION_END

Advanced Configuration

Hiding Native Menu Bar

Use Yabai's menubar_opacity setting in your .yabairc:

yabai -m config menubar_opacity 0.0

Keyboard Shortcuts

Aegis doesn't define global hotkeys - use skhd for that.

Example skhd configuration:

# Focus spaces
alt - 1 : yabai -m space --focus 1
alt - 2 : yabai -m space --focus 2
alt - 3 : yabai -m space --focus 3

# Move windows to space
shift + alt - 1 : yabai -m window --space 1
shift + alt - 2 : yabai -m window --space 2
shift + alt - 3 : yabai -m window --space 3

# Layout actions
alt - r : yabai -m space --rotate 90
alt - b : yabai -m space --balance
alt - t : yabai -m window --toggle float

Aegis will reflect all changes instantly via the FIFO pipe integration.

Excluded Apps

Some apps are automatically excluded from space indicators:

  • Aegis itself
  • Finder desktop
  • System UI elements

Import/Export Settings

To transfer settings between machines, copy:

  1. ~/.config/aegis/config.json (recommended - human-readable)
  2. ~/.config/aegis/ (includes yabai integration scripts)

Or export all current settings to JSON:

// In Xcode console or add temporarily to code:
AegisConfig.shared.saveToJSONFile()

This overwrites config.json with every setting and its current value.

Clone this wiki locally