This guide covers configuring, optimizing, and troubleshooting your macOS workstation with NREDF dotfiles, Homebrew, Kitty, and aqua across Apple Silicon (M1/M2/M3/M4) and Intel Macs.
Using chezmoi directly:
sh -c "$(curl -fsLS get.chezmoi.io)" -- -b ~/.local/bin init --apply NemesisRE/dotfilesOr using the bootstrap script:
bash <(curl -fsSL https://raw.githubusercontent.com/NemesisRE/dotfiles/main/bootstrap.sh)Prerequisites: Homebrew and Xcode Command Line Tools (
xcode-select --install).
NREDF automatically adapts all paths, compiler flags, and package locations based on your CPU architecture:
| Component | Apple Silicon (arm64) |
Intel (x86_64) |
|---|---|---|
| Homebrew Prefix | /opt/homebrew |
/usr/local |
| Homebrew Binaries | /opt/homebrew/bin |
/usr/local/bin |
| Homebrew Bash | /opt/homebrew/bin/bash |
/usr/local/bin/bash |
| Aqua Binaries | ~/.local/share/aquaproj-aqua/bin |
~/.local/share/aquaproj-aqua/bin |
Homebrew analytics and cleanup noise are disabled automatically in common/rc.tmpl:
HOMEBREW_NO_ANALYTICS=1HOMEBREW_NO_INSTALL_CLEANUP=1HOMEBREW_QUIET=1
Chezmoi manages native macOS packages and fonts declared in home/.chezmoidata/packages.yaml during chezmoi apply:
packages:
darwin:
brews:
- bash # Modern Bash 5.x (replaces Apple's legacy Bash 3.2)
- bash-completion@2 # Modern programmable completion
- git # Up-to-date Git client
- curl # Latest curl binary
- diffutils # GNU diff utilities
- util-linux # Linux utilities ported to macOS
casks:
- kitty # GPU-accelerated terminal emulator
- font-fira-mono-nerd-font # Primary Nerd Font matching editor & prompt- Pre-installed by Apple and configured as the default shell.
- NREDF configures Zsh with Sheldon plugin management, Oh-My-Posh prompt (
OneDark-Pro), Atuin history sync, and zoxide navigation.
- Apple ships an obsolete Bash 3.2 (from 2007) due to GPL licensing.
- NREDF Solution: When you start Bash,
.bashrc.tmpldetects Homebrew Bash (/opt/homebrew/bin/bashor/usr/local/bin/bash) and re-executes into it. - This unlocks ble.sh (Bash Line Editor), giving Bash real-time syntax highlighting, autosuggestions, and modern completion.
-
Install via Homebrew:
brew install --cask powershell
-
NREDF symlinks
~/.config/powershellto~/Documents/PowerShell, providing unified PSReadLine keybindings, PSFzf, Terminal-Icons, and Oh-My-Posh prompt parity.
Switch active shells on the fly anytime:
reload -s zsh # Switch to Zsh
reload -s bash # Switch to modern Bash 5
reload -s pwsh # Switch to PowerShellOn macOS, pressing Option + key (such as Option+c) by default outputs special characters (e.g. ç or ©) instead of sending a standard Meta/Escape sequence (\ec).
-
Kitty Terminal: Configured in
kitty.confwith:macos_option_as_alt both
Both Left and Right Option keys act as standard Alt keys.
-
Shell-Level Keybindings: If you use Terminal.app, iTerm2, or another terminal where Option still outputs special characters, NREDF binds both
çand©to directory jumping:- Zsh: Bound to
fzf-cd-widget - Bash (ble.sh): Bound via
ble-bind -c 'ç' 'eval "$(__fzf_cd__)"' - PowerShell: Bound via
Set-PSReadLineKeyHandler -Chord 'ç'
- Zsh: Bound to
Bitwarden Desktop on macOS provides a built-in SSH Agent socket. NREDF automatically checks and sets SSH_AUTH_SOCK to:
~/Library/Containers/com.bitwarden.desktop/Data/.bitwarden-ssh-agent.sock
(or ~/.bitwarden-ssh-agent.sock for the non-App-Store build). macOS' launchd always starts its own, usually empty, agent; with shell.ssh.agent: "default" NREDF prefers a running 1Password/Bitwarden agent over that launchd agent. Enable it in Bitwarden Desktop under Settings → SSH agent, keep the vault unlocked, and open a new shell. Set shell.ssh.agent: "bitwarden" to force it.
If configured for 1Password, NREDF automatically detects:
~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock
If you prefer modern Homebrew Bash or Zsh as your system-wide default login shell:
# Add Homebrew shell to allowed shells list
sudo sh -c 'echo "/opt/homebrew/bin/bash" >> /etc/shells'
# Change default login shell
chsh -s /opt/homebrew/bin/bashUse the yy alias to browse folders visually with syntax previews. When you quit Yazi with q, your terminal immediately switches to that folder!
Wondering why a shell starts slowly? Run:
reload -pInspect the exact startup breakdown in milliseconds across Homebrew, Oh-My-Posh, Atuin, and plugins.
NREDF installs a native user LaunchAgent (com.nredf.daily-sync.plist) that runs daily at 7:00 AM in the background (LowPriorityIO and Nice: 10). If the Mac is asleep at 7:00, launchd runs it on wake. If the Mac is shut down at 7:00, that day's run is skipped; run nredf-daily-sync or reload -f by hand to catch up.
- Upgrades Homebrew formulae and casks (
brew update && brew upgrade && brew cleanup -s). - Upgrades
chezmoiand runschezmoi apply --refresh-externals --force. If your secrets use a password safe that is locked (Bitwarden must be unlocked, for example withbwu), it skips the apply and logs why. - Updates
aquaand vacuums packages unused for >30 days. - Updates Sheldon Zsh plugin locks and the tldr page cache.
- Deletes oh-my-posh session caches older than 7 days.
- Logs full output to
~/.local/state/nredf/daily-sync.log. Anything printed before the script opens that log goes to~/Library/Logs/nredf-daily-sync.log.
Check agent status anytime:
launchctl list | grep nredfmacOS by default prints Last login: <date> on <tty> on every login shell, causing unnecessary I/O. NREDF installs an empty ~/.hushlogin to suppress this banner and accelerate terminal rendering.
Cause: Fresh macOS installations require Apple developer command-line tools for C compilers and Git headers.
Resolution: Run xcode-select --install and complete the Apple dialog prompt.
Cause: Permissions issue often occurring after macOS major OS upgrades. Resolution:
sudo chown -R $(whoami):admin /opt/homebrewCause: Apple Terminal does not support third-party font fallback for icons without manual configuration. Resolution:
- Use Kitty (installed automatically via Homebrew cask in
.chezmoidata/packages.yaml). - Or open Apple Terminal → Settings → Profiles → Font and select FiraCode Nerd Font Mono.