Installation

Choose Your Installation Method

Gentleman.Dots offers two installation approaches. The automatic installer is recommended for most users, while manual installation gives you complete control over every component.

Automatic Installation

Quick, interactive, handles everything for you (5-10 minutes)

Manual Installation

Step-by-step control over each component (20-30 minutes)

Automatic Installation

The automatic installer is an interactive bash script that detects your OS, asks for your preferences, and installs everything with progress indicators.

Prerequisites

macOS
Linux
Windows (WSL)

macOS 11.0 (Big Sur) or later
Xcode Command Line Tools will be installed automatically if missing

Installation Steps

Download the installer

Download the installation script from the repository:

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

This downloads the install-linux-mac.sh script to your current directory.

Make it executable

Grant execute permissions to the script:

sudo chmod +x install-linux-mac.sh

Run the installer

Execute the installation script:

bash ./install-linux-mac.sh

The script maintains sudo privileges automatically during installation. You’ll only need to enter your password once at the beginning.

Answer the prompts

The installer will ask you to choose:

Operating System: mac or linux
Terminal Emulator: alacritty, wezterm, kitty, ghostty, or none
Font Installation: Whether you already have Iosevka Term Nerd Font
Shell: fish, zsh, or nushell
Window Manager: tmux or zellij
Neovim: Whether to install and configure Neovim with AI

Which operating system are you using?
1) mac
2) linux
#? 1

Which terminal emulator do you want to install?
1) alacritty
2) wezterm
3) kitty
4) ghostty
5) none
#? 2

Do you already have Iosevka Term Nerd Font installed?
1) Yes
2) No
#? 2

Which shell do you want to install?
1) fish
2) zsh
3) nushell
#? 3

Which window manager do you want to install?
1) tmux
2) zellij
#? 1

Do you want to install Neovim?
1) Yes
2) No
#? 1

Wait for installation

The script will:

Clone the repository to ./Gentleman.Dots
Install Homebrew (if not present)
Install your chosen components
Copy configuration files to the correct locations
Set up AI tools (OpenCode, Claude Code, Gemini)
Configure your default shell
Clean up temporary files

Progress indicators show the status of each installation step.

Restart your shell

After installation completes, the script attempts to restart your shell automatically:

Configuration complete. Restarting shell...

If the shell doesn’t restart automatically:

# Restart your terminal or run:
exec $SHELL

# Or on Windows WSL, restart your terminal application

What Gets Installed

The automatic installer handles:

Core Dependencies

Homebrew package manager (macOS/Linux)
Rust toolchain via rustup
Node.js for Neovim plugins
Git, build tools, curl, wget

Terminal & Shell Tools

Your chosen terminal emulator:

# Alacritty
~/.config/alacritty/alacritty.toml

# WezTerm  
~/.config/wezterm/wezterm.lua

# Kitty (macOS only)
~/.config/kitty/

# Ghostty
~/.config/ghostty/

Shell configurations:

# Fish
~/.config/fish/config.fish

# Zsh
~/.zshrc
~/.p10k.zsh
~/.oh-my-zsh/

# Nushell
~/.config/nushell/config.nu  # Linux
~/Library/Application Support/nushell/  # macOS

Shell enhancements:

Starship prompt (~/.config/starship.toml)
Zoxide for directory jumping
Atuin for shell history
Carapace for completions
fzf for fuzzy finding

Window Manager

# Tmux
~/.tmux.conf
~/.tmux/plugins/  # TPM and plugins

# Zellij
~/.config/zellij/

Neovim & AI Tools

# Neovim configuration
~/.config/nvim/
├── init.lua
├── lua/
│   ├── config/
│   └── plugins/
└── stylua.toml

# OpenCode configuration
~/.config/opencode/
├── opencode.json
└── themes/gentleman.json

# Obsidian directory
~/.config/obsidian/
└── templates/

Neovim dependencies:

nvim, gcc, fzf, fd, ripgrep, bat, curl
lazygit, tree-sitter, coreutils
gemini-cli for Gemini integration

AI CLIs:

OpenCode CLI (curl -fsSL https://opencode.ai/install | bash)
Claude Code CLI (curl -fsSL https://claude.ai/install.sh | bash)

Fonts

Iosevka Term Nerd FontLinux:

~/.local/share/fonts/IosevkaTerm*

macOS:

# Installed via Homebrew Cask to system fonts
brew install --cask font-iosevka-term-nerd-font

Troubleshooting Automatic Install

Homebrew installation fails

If Homebrew installation gets stuck:

# Cancel the script (Ctrl+C) and install Homebrew manually:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Then re-run the installer
bash ./install-linux-mac.sh

Shell doesn't change after install

If the script couldn’t change your default shell:

# Manually change to your chosen shell
# For fish:
chsh -s $(which fish)

# For zsh:
chsh -s $(which zsh)

# For nushell:
chsh -s $(which nu)

# Verify:
echo $SHELL

Tmux plugins not installing

If Tmux plugins failed to install:

# Start tmux
tmux

# Inside tmux, press: Ctrl+a then I (capital i)
# This triggers TPM to install all plugins

Neovim errors on first launch

First launch might show errors while plugins install:

# Open Neovim
nvim

# Wait for Lazy.nvim to install all plugins
# Then quit and reopen:
:q
nvim

Manual Installation

Manual installation gives you complete control and helps you understand each component. Perfect for customization or learning.

Prerequisites

All platforms need:

Administrator/sudo privileges
Git installed
Internet connection

Clone the Repository

Clone Gentleman.Dots

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

All subsequent commands assume you’re in the Gentleman.Dots directory.

Platform-Specific Setup

macOS
Linux (Ubuntu/Debian)
Linux (Arch)
Windows (WSL)

Install Xcode Command Line Tools

xcode-select --install

Install Rust

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

Install Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
eval "$(/opt/homebrew/bin/brew shellenv)"

Install Iosevka Font

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

Update system and install build tools

sudo apt-get update
sudo apt-get install -y build-essential curl file git unzip fontconfig

Install Rust

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

Install Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.bashrc
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"

Install Iosevka Font

mkdir -p ~/.local/share/fonts
wget -O ~/.local/share/fonts/IosevkaTerm.zip https://github.com/ryanoasis/nerd-fonts/releases/download/v3.3.0/IosevkaTerm.zip
unzip ~/.local/share/fonts/IosevkaTerm.zip -d ~/.local/share/fonts/
fc-cache -fv

Update system and install dependencies

sudo pacman -Syu --noconfirm
sudo pacman -S --needed --noconfirm base-devel curl file git wget unzip fontconfig

Install Rust

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

Install Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.bashrc
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"

Install Iosevka Font

mkdir -p ~/.local/share/fonts
wget -O ~/.local/share/fonts/IosevkaTerm.zip https://github.com/ryanoasis/nerd-fonts/releases/download/v3.3.0/IosevkaTerm.zip
unzip ~/.local/share/fonts/IosevkaTerm.zip -d ~/.local/share/fonts/
fc-cache -fv

Install Terminal Emulator

Choose one terminal emulator:

Alacritty
WezTerm
Kitty
Ghostty

brew install alacritty --cask
mkdir -p ~/.config/alacritty
cp alacritty.toml ~/.config/alacritty/alacritty.toml

brew install wezterm --cask
mkdir -p ~/.config/wezterm
cp .wezterm.lua ~/.config/wezterm/wezterm.lua

brew install --cask kitty
mkdir -p ~/.config/kitty
cp -r GentlemanKitty/* ~/.config/kitty
# Reload config: Ctrl+Shift+, (or Cmd+Shift+, on Mac)

Kitty is only available for macOS through this installer.

brew install --cask ghostty
mkdir -p ~/.config/ghostty
cp -r GentlemanGhostty/* ~/.config/ghostty

Install Shell

Choose one shell and install it with its dependencies:

Nushell
Fish
Zsh

Copy environment files

cp -rf bash-env-json ~/.config/
cp -rf bash-env.nu ~/.config/

Install Nushell and tools

brew install nushell carapace zoxide atuin jq bash starship fzf
mkdir -p ~/.cache/starship
mkdir -p ~/.cache/carapace
mkdir -p ~/.local/share/atuin
cp -rf starship.toml ~/.config/

Configure Nushell

mkdir -p ~/Library/Application\ Support/nushell

# Update config for macOS
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/

brew install fish carapace zoxide atuin starship fzf
mkdir -p ~/.cache/starship
mkdir -p ~/.cache/carapace
mkdir -p ~/.local/share/atuin
cp -rf starship.toml ~/.config/
cp -rf GentlemanFish/fish ~/.config

brew install zsh carapace zoxide atuin fzf
brew install zsh-autosuggestions zsh-syntax-highlighting zsh-autocomplete
mkdir -p ~/.cache/carapace
mkdir -p ~/.local/share/atuin
cp -rf GentlemanZsh/.zshrc ~/
cp -rf GentlemanZsh/.p10k.zsh ~/
cp -rf GentlemanZsh/.oh-my-zsh ~/
brew install powerlevel10k

Install Window Manager

Tmux
Zellij

Install Tmux

brew install tmux

Install TPM (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'
# Wait a few seconds for installation
sleep 5
tmux kill-session -t plugin-installation

Or manually after starting tmux: Press Ctrl+a then I (capital i)

Install Zellij

brew install zellij

Or with Cargo:

cargo install zellij

Copy configuration

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

Update shell configuration

If using Zellij instead of Tmux, update your shell config:

# Update ~/.zshrc
if grep -q "TMUX" ~/.zshrc; then
  awk -v search="TMUX" -v replace='WM_VAR="/$ZELLIJ"' '
  $0 ~ search {print replace; next}
  {print}
  ' ~/.zshrc > ~/.zshrc.tmp && mv ~/.zshrc.tmp ~/.zshrc
else
  echo 'WM_VAR="/$ZELLIJ"' >> ~/.zshrc
fi

if grep -q "tmux" ~/.zshrc; then
  awk -v search="tmux" -v replace='WM_CMD="zellij"' '
  $0 ~ search {print replace; next}
  {print}
  ' ~/.zshrc > ~/.zshrc.tmp && mv ~/.zshrc.tmp ~/.zshrc
else
  echo 'WM_CMD="zellij"' >> ~/.zshrc
fi

Install Neovim

Create Obsidian directory

mkdir -p ~/.config/obsidian/templates

This directory will be used for note-taking with the Obsidian plugin.

Install Node.js (if needed)

# Check if Node.js is installed
node --version

# If not installed:
brew install node

Install AI CLI tools

# Install Claude Code
curl -fsSL https://claude.ai/install.sh | bash

# Install OpenCode
curl -fsSL https://opencode.ai/install | bash

# Install Gemini CLI
brew install gemini-cli

Configure OpenCode

mkdir -p ~/.config/opencode/themes
cp GentlemanOpenCode/opencode.json ~/.config/opencode/
cp GentlemanOpenCode/themes/gentleman.json ~/.config/opencode/themes/

Install Neovim and dependencies

brew install nvim git gcc fzf fd ripgrep coreutils bat curl lazygit tree-sitter

Copy Neovim configuration

mkdir -p ~/.config/nvim
cp -r GentlemanNvim/nvim/* ~/.config/nvim/

Configure Obsidian vault (optional)

Update the Obsidian plugin configuration with your vault path:

# Edit the config file
nvim ~/.config/nvim/lua/plugins/obsidian.lua

# Change this line:
# path = "/your/notes/path",
# To your actual path, for example:
# path = "~/.config/obsidian",

Launch Neovim

nvim

Lazy.nvim will automatically install all plugins on first launch. This may take a few minutes.

Set Default Shell

Find shell path

# For Fish
which fish

# For Zsh
which zsh

# For Nushell
which nu

Add shell to /etc/shells

# Replace SHELL_PATH with output from previous step
SHELL_PATH=$(which fish)  # or zsh, or nu

sudo sh -c "grep -Fxq \"$SHELL_PATH\" /etc/shells || echo \"$SHELL_PATH\" >> /etc/shells"

Change default shell

sudo chsh -s $SHELL_PATH $USER

On some systems, you may need to log out and back in for the change to take effect.

Verify

echo $SHELL
# Should show your new shell path

Restart Shell

# Restart your shell
exec $SHELL

# Or close and reopen your terminal

Windows WSL Setup

Windows users must complete these steps before running the automatic installer or following the manual installation guide.

Install WSL

Open PowerShell as Administrator and run:

wsl --install
wsl --set-default-version 2

Restart your computer when prompted.

Install Ubuntu

wsl --install -d Ubuntu

To see other available distributions:

wsl --list --online

To install a different distribution:

wsl --install -d <distribution-name>

Install Iosevka Font on Windows

Download Iosevka Term Nerd Font from Nerd Fonts GitHub
Extract the ZIP file
Right-click each .ttf or .otf font file
Select “Install for all users”

Install Terminal Emulator on Windows

Choose one:Alacritty:

Download from GitHub Releases
Place alacritty.exe in your PATH
Copy config:

mkdir $env:APPDATA\alacritty
Copy-Item -Path alacritty.toml -Destination $env:APPDATA\alacritty\alacritty.toml

In alacritty.toml, uncomment:

[shell]
program = "wsl.exe"
args = ["--cd", "~"]

WezTerm:

Download and install
Create environment variable HOME = C:\Users\your-username
Copy config:

Copy-Item -Path .wezterm.lua -Destination $HOME

In .wezterm.lua, uncomment:

config.default_domain = 'WSL:Ubuntu'
config.front_end = "WebGpu"
config.max_fps = 120

If WezTerm doesn’t load config:

mkdir $HOME\.config\wezterm
Copy-Item -Path .wezterm.lua -Destination $HOME\.config\wezterm\wezterm.lua

Kitty:

Download and install
Copy config:

Copy-Item -Path GentlemanKitty\* -Destination $HOME\.config\kitty -Recurse

Install Chocolatey and win32yank

In PowerShell as Administrator:

# Install Chocolatey
Set-ExecutionPolicy Bypass -Scope Process -Force; `
[System.Net.ServicePointManager]::SecurityProtocol = `
[System.Net.ServicePointManager]::SecurityProtocol -bor 3072; `
iwr https://community.chocolatey.org/install.ps1 -UseBasicParsing | iex

# Install win32yank (required for Neovim clipboard)
choco install win32yank

Launch WSL and update

Open your installed WSL distribution and update:

sudo apt-get update
sudo apt-get upgrade

Continue with installation

Now you can proceed with either the automatic installation or manual installation inside WSL.

Post-Installation

Verify installations

# Check shell
echo $SHELL

# Check Neovim
nvim --version

# Check window manager
tmux -V  # or: zellij --version

# Check AI tools
opencode --version
claude --version

Test AI integration

# Start OpenCode with Gentleman agent
opencode
# Type: /agent
# Select: gentleman

Customize (optional)

Edit ~/.config/nvim/lua/plugins/disabled.lua to switch AI plugins
Edit ~/.config/opencode/opencode.json to change models or agents
Customize colors in ~/.config/starship.toml

Next Steps

Quickstart Guide

Learn how to use your new development environment with practical examples

If you encounter any issues during installation, check the repository’s GitHub Issues or open a new issue with details about your system and the error.

Get Started

Terminal Emulators

Shells

Window Managers

Neovim Configuration

AI Integration

Platform-Specific Guides

Advanced

Choose Your Installation Method

Automatic Installation

Manual Installation

Automatic Installation

Prerequisites

Installation Steps

What Gets Installed

Troubleshooting Automatic Install

Manual Installation

Prerequisites

Clone the Repository

Platform-Specific Setup

Install Terminal Emulator

Install Shell

Install Window Manager

Install Neovim

Set Default Shell

Restart Shell

Windows WSL Setup

Post-Installation

Next Steps

Quickstart Guide

Build docs developers (and LLMs) love

Get Started

Terminal Emulators

Shells

Window Managers

Neovim Configuration

AI Integration

Platform-Specific Guides

Advanced

​Choose Your Installation Method

Automatic Installation

Manual Installation

​Automatic Installation

​Prerequisites

​Installation Steps

​What Gets Installed

​Troubleshooting Automatic Install

​Manual Installation

​Prerequisites

​Clone the Repository

​Platform-Specific Setup

​Install Terminal Emulator

​Install Shell

​Install Window Manager

​Install Neovim

​Set Default Shell

​Restart Shell

​Windows WSL Setup

​Post-Installation

​Next Steps

Quickstart Guide

Build docs developers (and LLMs) love

Choose Your Installation Method

Automatic Installation

Prerequisites

Installation Steps

What Gets Installed

Troubleshooting Automatic Install

Manual Installation

Prerequisites

Clone the Repository

Platform-Specific Setup

Install Terminal Emulator

Install Shell

Install Window Manager

Install Neovim

Set Default Shell

Restart Shell

Windows WSL Setup

Post-Installation

Next Steps