Ultimate ZSH Setup — Apple M4 MacBook Pro 2026

Stack: Ghostty · Antidote · Starship · Modern CLI tools
Package manager: Homebrew (everything)
Target: macOS Sequoia / Tahoe · ARM64 (Apple Silicon)

---

Files in this bundle

File	Destination	Purpose
install.sh	Run once	Master installer — installs all tools via Homebrew
ghostty.config	~/.config/ghostty/config	Ghostty terminal config
starship.toml	~/.config/starship.toml	Starship prompt config
.zshrc	~/.zshrc	Main ZSH interactive config
.zshenv	~/.zshenv	ZSH environment (all invocations)
.zsh_plugins.txt	~/.zsh_plugins.txt	Antidote plugin list
.aliases.zsh	~/.aliases.zsh	All shell aliases

---

Quick install

# 1 — Clone / download this folder
cd ~/Downloads/zsh-setup

# 2 — Make installer executable
chmod +x install.sh

# 3 — Run it (will ask for sudo password once for /etc/shells)
./install.sh

# 4 — Open Ghostty, then reload shell
exec zsh

---

What gets installed

Terminal

• Ghostty brew install --cask ghostty — GPU-accelerated, Metal-native, Claude Code compatible

Shell & Plugin Manager

• zsh brew install zsh — latest version (macOS ships older)
• antidote brew install antidote — static plugin loader, ~18x faster than oh-my-zsh

Prompt

• starship brew install starship — Rust-based, cross-shell, 2–3ms per prompt

Font

• JetBrainsMono Nerd Font brew install --cask font-jetbrains-mono-nerd-font
  Required for Starship icons and eza file icons

Modern CLI tools

Tool	Replaces	Install
eza	ls	brew install eza
bat	cat	brew install bat
fzf	Ctrl+R / find	brew install fzf
fd	find	brew install fd
ripgrep	grep	brew install ripgrep
zoxide	cd / autojump	brew install zoxide
git-delta	diff	brew install git-delta
btop	top	brew install btop
fastfetch	neofetch	brew install fastfetch
jq	—	brew install jq
yq	—	brew install yq
tldr	man	brew install tldr
hishtory	history	brew install hishtory
git	Apple git	brew install git
gh	—	brew install gh
tmux	—	brew install tmux
mise	nvm/pyenv/rbenv	brew install mise
direnv	—	brew install direnv
xh	curl	brew install xh
mas	App Store GUI	brew install mas

---

Compatibility analysis: Starship + Antidote + Ghostty

Zero conflicts. Here's why each combination works:

Starship ↔ Antidote

Starship is initialized via eval "$(starship init zsh)" at the end of .zshrc, after antidote has loaded all plugins. This is the correct order because:

• Antidote's deferred plugins (kind:defer) use zsh-defer to load after the first prompt. Starship hooks into PROMPT — both coexist on the same precmd hook chain without conflict.
• fast-syntax-highlighting and zsh-autosuggestions operate on ZLE (Zsh Line Editor) widgets, not on the prompt itself. Starship only touches $PROMPT and $RPROMPT.
• zsh-history-substring-search binds ↑/↓ keys — no overlap with Starship.

Starship ↔ Ghostty

Ghostty has shell-integration = detect which injects shell integration via a sourced script. This integration adds semantic marks (jump-to-prompt) by hooking into precmd/preexec. Starship also uses precmd. The load order is:

1. Ghostty shell integration (injected automatically)
2. Antidote plugins (via static file)
3. Starship init (last line of .zshrc)

Ghostty's integration is designed to be compatible with prompt frameworks including Starship — it does not override $PROMPT, only appends OSC escape sequences. No conflict.

Antidote ↔ zoxide / direnv / mise

These tools use eval "$(tool init zsh)" which adds their own precmd/chpwd hooks. Antidote has no opinion on these — it only sources plugin files. No conflict.

Font: JetBrains Mono Nerd Font ↔ Starship ↔ eza

Both Starship and eza require a Nerd Font to render icons correctly. JetBrainsMono Nerd Font is configured in ghostty.config as font-family. Ghostty uses CoreText on macOS — font rendering is handled natively. All three work together.

---

Plugin load order explanation

.zshrc execution order:
1. brew shellenv           → Homebrew PATH
2. History & ZSH options   → setopt flags
3. zstyle completions      → Completion config (before compinit)
4. antidote               → Sources ~/.zsh_plugins.zsh (static file)
   ├── getantidote/use-omz → OMZ compatibility shim
   ├── ohmyzsh plugins     → git, brew, docker, etc. (immediate)
   ├── zsh-completions     → fpath only (before compinit)
   ├── ez-compinit         → runs compinit (end of fpath plugins)
   └── (deferred via zsh-defer, after first prompt):
       ├── zsh-autosuggestions
       ├── fast-syntax-highlighting
       └── zsh-history-substring-search
5. fzf keybindings         → Ctrl+R, Ctrl+T, Alt+C
6. zoxide init             → replaces cd
7. mise activate           → version manager shims
8. direnv hook             → .env auto-loader
9. source ~/.aliases.zsh   → all aliases
10. starship init zsh      → LAST: sets $PROMPT

---

Common operations after install

# Add a new plugin
echo "author/repo" >> ~/.zsh_plugins.txt
antidote update   # regenerates static file

# Update all plugins
antidote update

# Update all brew tools
brewup            # alias for: brew update && brew upgrade && brew upgrade --cask --greedy && brew cleanup

# Reload shell without restart
reload            # alias for: exec zsh

# Benchmark startup time
zsh-bench-me      # alias for 5x time zsh -ic exit

# Edit configs
zshrc             # opens ~/.zshrc in $EDITOR
ghosttycfg        # opens ~/.config/ghostty/config
starshipcfg       # opens ~/.config/starship.toml

# Reload Ghostty config without restart
# In Ghostty: Cmd+Shift+, (comma)

---

Starship modules active by default

Module	Shows	When
os	Apple icon	Always
directory	Current path (truncated)	Always
git_branch	Branch name	In git repos
git_status	?, !, +, ⇡, ⇣	In git repos
git_metrics	+added / -deleted	In git repos
nodejs	Node version	When package.json present
python	Python version + venv	When .py files present
golang	Go version	When .go files present
rust	Rust version	When .rs files present
docker_context	Docker context	When Dockerfile present
time	HH:MM	Always (right side)
status	Exit code	On error only
character	❯ green / ❯ red	Based on last exit code

---

Troubleshooting

Icons not showing?
→ Ensure Ghostty font is set to JetBrainsMono Nerd Font in ~/.config/ghostty/config

Antidote plugins not loading?
→ Run antidote update to regenerate the static file
→ Check: cat ~/.zsh_plugins.zsh to see what was generated

Slow startup?
→ Run zsh-bench-me to measure
→ Profile with: zsh -i -c 'zprof' 2>&1 | head -30 (add zmodload zsh/zprof at top of .zshrc first)

Starship not showing?
→ Verify eval "$(starship init zsh)" is the LAST line of .zshrc
→ Check: which starship → should return /opt/homebrew/bin/starship

Ghostty global hotkey (Cmd+`) not working?
→ Go to System Preferences → Privacy & Security → Accessibility → Grant Ghostty access