macOS Dotfiles

A collection of configuration files for my macOS setup, managed with Git.

🛠 Configuration Included

Window Management & Status Bar

• AeroSpace: Alternative tiling WM configuration in .config/aerospace/.
  • Kept as a supported fallback path.
  • Auto-start is currently disabled, so it can be launched manually when needed.
• yabai + skhd: Current native-Spaces WM stack in .config/yabai/ and .config/skhd/.
  • 10 numbered workspaces.
  • skhd hotkeys follow the same Dvorak-style movement pattern used in the older AeroSpace setup.
  • App-specific helpers handle odd windows like ChatGPT Atlas and picker dialogs.
• WM glue scripts: Shared helpers in .config/wm/ keep workspace actions and WM switching consistent.
  • focus-workspace and move-window-to-workspace dispatch to the active WM.
  • set-window-manager flips between aerospace and yabai.
  • toggle-movie-mode handles IINA fullscreen behavior.
• SketchyBar: Status bar configuration in .config/sketchybar/.
  • Custom Lua configuration.
  • Loads AeroSpace or yabai workspace modules automatically based on the selected WM.
  • Widgets: CPU, RAM, Battery, Volume, WiFi (with WAN IP), Brew updates.

Terminal & Shell

• Zsh: Shell configuration (.zshrc, .zprofile, .zshenv).
  • Powerlevel10k: Theme configuration (.p10k.zsh).
  • Modern CLI tools: bat (cat), eza (ls), atuin (history), direnv (env management), zoxide (cd).
• WezTerm: Primary terminal emulator (.config/wezterm/).
  • Zellij integration keybindings.
• Ghostty: Alternative terminal emulator (.config/ghostty/).
  • Custom shaders and themes.
• Zellij: Terminal multiplexer (.config/zellij/).
  • Session management with custom aliases (zm, tml, tmk).
  • Locked mode by default for seamless shell usage.
  • 3-tab project layout (shell, claude, nvim).
• Fastfetch: System information fetch tool (.config/fastfetch/).
• Git: Global git configuration (.config/git/).

Utilities

• Raycast: Productivity tool extensions and scripts (.config/raycast/).
• Karabiner-Elements: Keyboard customization (.config/karabiner/).
  • Caps Lock → Escape.
  • Built-in keyboard Option+1..0 and Option+Shift+1..0 route through shared WM scripts, so the same workspace keys work for AeroSpace and yabai.

⌨️ Keybindings

Quick access to keyboard shortcuts:

• Karabiner keybindings - Physical key remapping, modifier setup
• Shell (Zsh) keybindings - Terminal navigation, history, editing
• AeroSpace keybindings - Older workspace and layout reference
• skhd keybindings - Current yabai hotkeys for focus, moving, workspaces, and fullscreen
• WezTerm keybindings - Terminal emulator shortcuts
• Zellij keybindings - Session management, tab/pane navigation
• NvChad keybindings - Neovim editor shortcuts

Full reference: .config/KEYBINDINGS.md plus the live skhd config.

🚀 Setup

1. Clone the repository:

   git clone git@github.com:xajler/mac-dotfiles.git ~/mac-dotfiles
   # Or if you are cloning directly to home (be careful with existing files):
   # git init
   # git remote add origin ...
   # git pull origin master

2. Secrets Management:

   Create or copy .zsh.env file for private aliases and secrets (ignored by git):

   Secrets are stored in macOS Keychain for security. See Security section below.

   Note: .zsh.env is gitignored to keep your private settings safe.

3. Choose a window manager path:

   AeroSpace

   open -a AeroSpace
   ~/.config/wm/set-window-manager aerospace

   yabai + skhd

   • Install yabai and skhd.
   • Grant Accessibility permissions to both binaries.
   • If using the scripting addition features, follow the upstream yabai SIP instructions first.
   • Then switch to it:

   ~/.config/wm/set-window-manager yabai

   SketchyBar will reload against the selected WM automatically.

🔀 Window Manager Switching

The repo supports both AeroSpace and yabai/skhd.

• Current WM selection is stored locally in ~/.local/state/wm/window-manager.
• Shared scripts in .config/wm/ use that state so workspace keybindings keep working across both stacks.
• SketchyBar reads the same state and loads either .config/sketchybar/items/aerospace.lua or .config/sketchybar/items/yabai_spaces.lua.

Useful commands:

~/.config/wm/current-window-manager
~/.config/wm/set-window-manager yabai
~/.config/wm/set-window-manager aerospace

📂 Structure

• .config/: Application configurations.
• .config/wm/: Shared helpers for WM switching, workspace routing, movie mode, Atlas sizing, and picker dialogs.
• .zshrc: Main shell configuration with Keychain integration.
• .zsh.env: Private aliases and settings (not tracked).
• .gitignore: Custom ignore rules for dotfiles management.

🔐 Security

Sensitive data (API tokens, credentials) is stored in macOS Keychain, not in plain text files. The .zsh.env file loads these secrets on shell startup.

Adding Secrets to Keychain

To store a new secret:

security add-generic-password -U -a "$USER" -s "SECRET_NAME" -w "your-secret-value"

Then add to your .zsh.env:

export SECRET_NAME=$(security find-generic-password -a "$USER" -s "SECRET_NAME" -w 2>/dev/null)

Benefits:

• Secrets encrypted by macOS Keychain
• No plain text tokens in dotfiles
• Safe to commit .zshrc to public repos
• Private settings stay in gitignored .zsh.env

🔑 SSH Keys

SSH keys use macOS Keychain for passphrase storage and .zprofile for eager loading in login zsh sessions.

Setup (One-time)

1. Configure SSH to use Keychain (already in .ssh/config):

   Host *
     AddKeysToAgent yes
     UseKeychain yes
   

   GitHub host aliases should also pin the intended key with IdentitiesOnly yes.

2. Add your SSH keys to Keychain once:

   ssh-add --apple-use-keychain ~/.ssh/id_ed25519_metaintellect
   ssh-add --apple-use-keychain ~/.ssh/id_ed25519_aenetworks
   ssh-add --apple-use-keychain ~/.ssh/id_ed25519

   This stores the passphrases securely in macOS Keychain.

3. Verify a fresh login shell can load them:

   ssh-add -l
   zsh -lc 'ssh-add -l'

How it works:

• Keychain stores the passphrases securely
• .zprofile eagerly loads the three keys for login zsh sessions, including zsh -lc
• This covers Terminal and Codex-style login shells without managing SSH_AUTH_SOCK manually
• If keys must exist before any shell starts, use a macOS LaunchAgent instead of shell startup files

🖥️ macOS System Settings

Night Shift - Force 24/7 Warm Display

macOS Night Shift UI can't be set to truly 24/7 (leaves a 1-minute gap at midnight). Force it always on:

# Enable Night Shift permanently
defaults write com.apple.CoreBrightness "CBBlueReductionStatus" -dict-add "BlueReductionEnabled" -bool YES "BlueReductionMode" -int 0 "AutoBlueReductionEnabled" -bool NO

# Restart display service to apply
killall corebrightnessdiagnostics 2>/dev/null || true

System Settings UI: Ignore the schedule settings - the command overrides them. You can still adjust the warmth slider.

To revert: Toggle Night Shift off/on in System Settings → Displays → Night Shift.

📝 License

GPLv3