macOS Installation Guide

Overview

This guide covers the installation of Gentleman.Dots on macOS systems. The setup includes terminal emulators, shells, window managers, and Neovim with AI integrations optimized for macOS.

Want bleeding edge features? Check out the nix-migration branch for the latest experimental macOS-focused configurations. Note that it may have occasional instabilities.

Prerequisites

Before starting the installation, ensure you have:

macOS 10.15 (Catalina) or later
Administrator privileges
Internet connection for downloading packages
At least 2GB of free disk space
Xcode Command Line Tools (installed automatically during setup)

Installation Methods

Automatic Installation

Recommended: Use the automated script for quick setup

Manual Installation

Step-by-step manual configuration for advanced users

Automatic Installation

The automated installation script is the quickest way to get started with Gentleman.Dots on macOS.

You must install the Iosevka Term Nerd Font before running the script. The font is required for proper terminal display.

Download the Installation Script

Download the automated installation script from the repository:

curl -O https://raw.githubusercontent.com/Gentleman-Programming/Gentleman.Dots/refs/heads/main/install-linux-mac.sh

Make the Script Executable

Grant execution permissions to the script:

sudo chmod +x install-linux-mac.sh

Run the Installation

Execute the script and follow the interactive prompts:

bash ./install-linux-mac.sh

The script will:

Install Xcode Command Line Tools (if needed)
Install Rust and Homebrew
Configure your chosen terminal emulator (Alacritty, WezTerm, Kitty, or Ghostty)
Set up your selected shell (Fish, Zsh, or Nushell)
Install your preferred window manager (Tmux or Zellij)
Configure Neovim with AI integrations (OpenCode, Claude Code, Gemini)

Restart Your Terminal

After installation completes, restart your terminal:

exec $SHELL

Manual Installation

Install Xcode Command Line Tools

Install the Xcode Command Line Tools (required for compilation):

xcode-select --install

Follow the prompts to complete the installation.

Clone the Repository

Clone the Gentleman.Dots repository:

git clone [email protected]:Gentleman-Programming/Gentleman.Dots.git
cd Gentleman.Dots

Install Rust

Install Rust programming language:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
. $HOME/.cargo/env

Install Homebrew

Install Homebrew package manager:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Add Homebrew to your PATH
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.bashrc
eval "$(/opt/homebrew/bin/brew shellenv)"

Install Iosevka Term Nerd Font

Install the required Nerd Font using Homebrew:

brew tap homebrew/cask-fonts
brew install --cask font-iosevka-term-nerd-font

Choose and Install a Terminal Emulator

Select one of the following terminal emulators:

Alacritty
WezTerm
Kitty
Ghostty

brew install alacritty --cask

# Copy configuration
mkdir -p ~/.config/alacritty
cp alacritty.toml ~/.config/alacritty/alacritty.toml

brew install wezterm --cask

# Copy configuration
mkdir -p ~/.config/wezterm
cp .wezterm.lua ~/.config/wezterm/wezterm.lua

brew install --cask kitty

# Copy configuration
mkdir -p ~/.config/kitty
cp -r GentlemanKitty/* ~/.config/kitty

After installation, reload Kitty’s config with Cmd+Shift+,

brew install --cask ghostty

# Copy configuration
mkdir -p ~/.config/ghostty
cp -r GentlemanGhostty/* ~/.config/ghostty

Choose and Install a Shell

Select and configure your preferred shell:

Nushell
Fish
Zsh

# Install Nushell and dependencies
brew install nushell carapace zoxide atuin jq bash starship fzf

# Create directories
mkdir -p ~/.cache/starship
mkdir -p ~/.cache/carapace
mkdir -p ~/.local/share/atuin

# Copy configuration files
cp -rf bash-env-json ~/.config/
cp -rf bash-env.nu ~/.config/
cp -rf starship.toml ~/.config/

# Copy Nushell config (macOS-specific location)
mkdir -p ~/Library/Application\ Support/nushell

# Update config for macOS Homebrew path
if grep -q "/home/linuxbrew/.linuxbrew/bin" GentlemanNushell/env.nu; then
  awk -v search="/home/linuxbrew/.linuxbrew/bin" -v replace="    | prepend '/opt/homebrew/bin'" '
  $0 ~ search {print replace; next}
  {print}
  ' GentlemanNushell/env.nu > GentlemanNushell/env.nu.tmp && mv GentlemanNushell/env.nu.tmp GentlemanNushell/env.nu
else
  echo "    | prepend '/opt/homebrew/bin'" >> GentlemanNushell/env.nu
fi

cp -rf GentlemanNushell/* ~/Library/Application\ Support/nushell/

# Install Fish and dependencies
brew install fish carapace zoxide atuin starship fzf

# Create directories
mkdir -p ~/.cache/starship
mkdir -p ~/.cache/carapace
mkdir -p ~/.local/share/atuin

# Copy configuration
cp -rf starship.toml ~/.config/
cp -rf GentlemanFish/fish ~/.config

# Install Zsh and dependencies
brew install zsh carapace zoxide atuin fzf
brew install zsh-autosuggestions zsh-syntax-highlighting zsh-autocomplete

# Create directories
mkdir -p ~/.cache/carapace
mkdir -p ~/.local/share/atuin

# Copy configuration
cp -rf GentlemanZsh/.zshrc ~/
cp -rf GentlemanZsh/.p10k.zsh ~/
cp -rf GentlemanZsh/.oh-my-zsh ~/

# Install PowerLevel10k
brew install powerlevel10k

Zsh is the default shell on macOS. The configuration adds PowerLevel10k for an enhanced prompt.

Choose and Install a Window Manager

Select either Tmux or Zellij:

Tmux
Zellij

# Install Tmux
brew install tmux

# Install Tmux Plugin Manager
git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

# Copy configuration
mkdir -p ~/.tmux
cp -r GentlemanTmux/.tmux/* ~/.tmux/
cp GentlemanTmux/.tmux.conf ~/

# Install plugins
tmux new-session -d -s plugin-installation 'source ~/.tmux.conf; tmux run-shell ~/.tmux/plugins/tpm/bin/install_plugins'
tmux kill-session -t plugin-installation

# Install Zellij
brew install zellij

# Copy configuration
mkdir -p ~/.config/zellij
cp -r GentlemanZellij/zellij/* ~/.config/zellij/

If using Zellij with Nushell, update the config to use Zellij instead of Tmux.

Install Neovim

Install Neovim and all required dependencies:

# Install core dependencies
brew install nvim node npm git gcc fzf fd ripgrep coreutils bat curl lazygit tree-sitter

# Install AI CLI tools
curl -fsSL https://opencode.ai/install | bash
curl -fsSL https://claude.ai/install.sh | bash
brew install gemini-cli

# Copy Neovim configuration
mkdir -p ~/.config/nvim
cp -r GentlemanNvim/nvim/* ~/.config/nvim/

# Configure OpenCode with Gentleman theme and agent
mkdir -p ~/.config/opencode/themes
cp GentlemanOpenCode/opencode.json ~/.config/opencode/
cp GentlemanOpenCode/themes/gentleman.json ~/.config/opencode/themes/

# Configure Obsidian path (optional)
mkdir -p ~/.config/obsidian/templates
nvim ~/.config/nvim/lua/plugins/obsidian.lua
# Update the path field to your Obsidian vault location

Set Default Shell

Set your chosen shell as the default:

shell_path=$(which fish)
sudo sh -c "grep -Fxq \"$shell_path\" /etc/shells || echo \"$shell_path\" >> /etc/shells"
sudo chsh -s "$shell_path" "$USER"

Restart Your Terminal

Restart your terminal for all changes to take effect:

exec $SHELL

macOS-Specific Considerations

Homebrew Paths

On Apple Silicon Macs (M1/M2/M3), Homebrew installs to /opt/homebrew. On Intel Macs, it installs to /usr/local. The installation script handles this automatically.

Nushell Configuration Location

Unlike Linux, Nushell configuration on macOS is stored in:

~/Library/Application Support/nushell/

The installation script automatically handles this difference.

Terminal Emulator Integration

All terminal emulators integrate seamlessly with macOS features:

Kitty: Full support for macOS keyboard shortcuts
Alacritty: Native macOS window management
WezTerm: macOS menu bar integration
Ghostty: Optimized for macOS performance

System Preferences

For the best experience, enable “Use Option as Meta key” in your Terminal preferences. This allows proper key binding functionality in Neovim and other CLI tools.

Troubleshooting

Xcode Command Line Tools installation fails

If Xcode installation fails:

Try installing from the App Store:
- Open the App Store
- Search for “Xcode”
- Install the full Xcode application

Then install command line tools:

sudo xcode-select --reset
xcode-select --install

Homebrew installation issues on Apple Silicon

If Homebrew doesn’t work on M1/M2/M3 Macs:

Ensure the correct path is in your shell config:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc

Verify Homebrew is accessible:

which brew
# Should output: /opt/homebrew/bin/brew

Terminal emulator won't launch

If your terminal emulator fails to start:

Check if it’s allowed in Security & Privacy:
- Open System Preferences → Security & Privacy
- Check if the app is blocked
- Click “Open Anyway” if needed

Reset the app:

# For Kitty
rm -rf ~/.config/kitty
cp -r GentlemanKitty/* ~/.config/kitty

Permission errors during installation

If you encounter permission errors:

# Fix Homebrew permissions
sudo chown -R $(whoami) $(brew --prefix)/*

# Fix config directory permissions
sudo chown -R $(whoami) ~/.config

Node.js or AI CLI tools not working

If AI integrations aren’t working:

Verify Node.js version:
```
node --version  # Should be 18+
```

Reinstall AI CLI tools:

curl -fsSL https://opencode.ai/install | bash
curl -fsSL https://claude.ai/install.sh | bash

Check PATH configuration:
```
echo $PATH | grep opencode
```

Next Steps

Customize Your Setup

Learn how to customize terminal colors, key bindings, and more

Neovim Configuration

Explore Neovim features and AI integrations

Explore Nix Branch

Check out the experimental nix-migration branch for cutting-edge features

Join the Community

Get help and share your setup with the community

After installation, the Gentleman.Dots configuration is ready to use! Try opening Neovim and exploring the AI integrations by typing /agent in OpenCode to select the Gentleman agent.

Get Started

Terminal Emulators

Shells

Window Managers

Neovim Configuration

AI Integration

Platform-Specific Guides

Advanced

Overview

Prerequisites

Installation Methods

Automatic Installation

Manual Installation

Automatic Installation

Manual Installation

macOS-Specific Considerations

Homebrew Paths

Nushell Configuration Location

Terminal Emulator Integration

System Preferences

Troubleshooting

Next Steps

Customize Your Setup

Neovim Configuration

Explore Nix Branch

Join the Community

Build docs developers (and LLMs) love

Get Started

Terminal Emulators

Shells

Window Managers

Neovim Configuration

AI Integration

Platform-Specific Guides

Advanced

​Overview

​Prerequisites

​Installation Methods

Automatic Installation

Manual Installation

​Automatic Installation

​Manual Installation

​macOS-Specific Considerations

​Homebrew Paths

​Nushell Configuration Location

​Terminal Emulator Integration

​System Preferences

​Troubleshooting

​Next Steps

Customize Your Setup

Neovim Configuration

Explore Nix Branch

Join the Community

Build docs developers (and LLMs) love

Overview

Prerequisites

Installation Methods

Automatic Installation

Manual Installation

macOS-Specific Considerations

Homebrew Paths

Nushell Configuration Location

Terminal Emulator Integration

System Preferences

Troubleshooting

Next Steps