Terminal Setup Guide

A comprehensive guide to replicate my terminal setup with Ghostty, Starship prompt, Zsh, and custom themes.

Prerequisites

• macOS (this guide is macOS-specific)
• Homebrew package manager

---

Quick Start

# Clone this repository
git clone https://github.com/yourusername/terminal-config-guide.git
cd terminal-config-guide

# Install JetBrains Mono Nerd Font
brew install font-jetbrains-mono-nerd-font

# Install Ghostty terminal emulator
brew install --cask ghostty

# Copy Ghostty config and themes
mkdir -p ~/.config/ghostty
cp ghostty/config ~/.config/ghostty/config
cp -r ghostty/themes ~/.config/ghostty/

# Install Oh My Zsh framework
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

# Install zsh-autosuggestions plugin
git clone https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions

# Install fast-syntax-highlighting plugin
git clone https://github.com/zdharma-continuum/fast-syntax-highlighting.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/fast-syntax-highlighting

# Install zsh-vi-mode plugin
git clone https://github.com/jeffreytse/zsh-vi-mode ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-vi-mode

# Install zsh-defer plugin
git clone https://github.com/romkatv/zsh-defer.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-defer

# Install Starship prompt
brew install starship

# Copy Starship configuration
cp configs/starship.toml ~/.config/starship.toml

# Copy minimal zsh configuration (or merge with your existing .zshrc)
cp configs/.zshrc-minimal ~/.zshrc

# Reload shell configuration
source ~/.zshrc

# Optional: Install FZF for fuzzy finding
brew install fzf

# Optional: Install Atuin for advanced history search
brew install atuin

# Optional: Install Carapace for better completions
brew install carapace

Done! Open a new Ghostty terminal window to see your new setup.

For detailed explanations and customization options, see the sections below.

---

Screenshots

Atuin

Carapace

---

Phase 1: Nerd Fonts Installation

JetBrains Mono Nerd Font (Primary)

Option 1: Homebrew (Recommended)

brew install font-jetbrains-mono-nerd-font

Option 2: Manual Download

• Download: JetBrains Mono Nerd Font
• Search for JetBrainsMono.zip in the assets
• Extract and install the .ttf files by double-clicking them

Alternative Font: IosevkaTerm Nerd Font

brew install font-iosevka-term-nerd-font

---

Phase 2: Ghostty Terminal Emulator

Download & Install

Official Website:

• https://ghostty.org

Homebrew:

brew install --cask ghostty

GitHub Releases:

• https://github.com/ghostty-org/ghostty/releases

Configuration

1. Create config directory:

mkdir -p ~/.config/ghostty

2. Copy the config file from this repo to ~/.config/ghostty/config

3. Copy the themes directory to ~/.config/ghostty/themes/

Key Features:

• Font: JetBrains Mono Nerd Font, size 21
• Active Theme: Night Owl
• Shell integration with zsh
• Custom split pane keybindings
• Opacity and alpha blending settings

---

Phase 3: Zsh Setup

Install Oh My Zsh

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

Install Essential Plugins

1. zsh-autosuggestions

git clone https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions

2. fast-syntax-highlighting

git clone https://github.com/zdharma-continuum/fast-syntax-highlighting.git \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/fast-syntax-highlighting

3. zsh-vi-mode

git clone https://github.com/jeffreytse/zsh-vi-mode \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-vi-mode

4. zsh-defer

git clone https://github.com/romkatv/zsh-defer.git \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-defer

Configure .zshrc

Use the minimal .zshrc configuration from this repo, which includes:

• Plugin initialization
• Vi-mode settings (jk to escape, Ctrl+L to accept suggestions)
• Basic PATH and environment variables

---

Phase 4: Starship Prompt

Install Starship

brew install starship

Configuration

1. Copy starship.toml from this repo to ~/.config/starship.toml

2. Add to your .zshrc:

eval "$(starship init zsh)"

Features:

• Gradient modern color palette (coral → orange → yellow → teal → blue → purple)
• OS icon and username display
• Directory with icons
• Git branch and status
• Language version indicators (Node, PHP, Python, Rust, etc.)
• Custom vim mode indicators with Nerd Font icons

---

Phase 5: Optional Tools

These tools significantly enhance your terminal workflow but aren't required for the basic setup.

---

1. FZF (Fuzzy Finder)

What it does:
FZF is a blazing-fast command-line fuzzy finder that lets you quickly search through files, command history, processes, and more with interactive filtering.

Installation:

brew install fzf

Configuration:

Add to your .zshrc:

# FZF integration
source <(fzf --zsh)

# Optional: Bind Ctrl+T to file search widget
bindkey '^T' fzf-file-widget

Key Features:

• Ctrl+R: Search command history interactively
• Ctrl+T: Fuzzy find files in current directory
• Alt+C: Fuzzy find and cd into directories
• Works with any list input via pipe: ls | fzf

Customization (Optional):

# Add to .zshrc for better defaults
export FZF_DEFAULT_OPTS="--height 40% --layout=reverse --border"
export FZF_DEFAULT_COMMAND='fd --type f --hidden --follow --exclude .git'

---

2. Atuin (Shell History Search & Sync)

What it does:
Atuin replaces your default shell history with a searchable, syncable SQLite database. It provides context-aware history search with timestamps, directories, and duration tracking.

Installation:

brew install atuin

Configuration:

1. Initialize Atuin:

atuin init zsh

2. Add to your .zshrc:

# Atuin history search
eval "$(atuin init zsh)"

# Custom keybindings (vi-mode compatible)
bindkey -M viins '^r' atuin-search  # Ctrl+R in insert mode
bindkey -M vicmd '/' atuin-search   # / in normal mode

3. (Optional) Register for sync:

atuin register -u <your-username> -e <your-email>
atuin login -u <your-username>
atuin sync

Key Features:

• Full-text search across all command history
• Shows command duration and exit codes
• Sync history across multiple machines
• Filter by directory or session
• Privacy-focused (optional encrypted sync)

Example Usage:

• Press Ctrl+R → Type partial command → Fuzzy search through history
• Filter by directory: Atuin only shows commands run in current dir

---

3. Carapace (Advanced Completion Engine)

What it does:
Carapace is a multi-shell completion generator that provides intelligent, context-aware completions for 1000+ CLI tools. It bridges completions from Fish, Bash, and Zsh.

Installation:

brew install carapace

Configuration:

Add to your .zshrc:

# Carapace completion engine
export CARAPACE_BRIDGES='zsh,fish,bash,inshellisense'
source <(carapace _carapace)

Key Features:

• Rich completions for tools like git, docker, npm, cargo, etc.
• Dynamic argument suggestions (e.g., branch names, file paths)
• Multi-shell bridge support
• Faster than native completions in many cases

Example:

# Type and press TAB for intelligent suggestions:
git checkout <TAB>        # Shows branches
docker ps <TAB>           # Shows container options
npm run <TAB>             # Shows package.json scripts

---

Summary: Which Optional Tools Should You Install?

Tool	Use Case	Install If...
FZF	File/history search	You frequently search files or history
Atuin	Advanced history	You want searchable, syncable history across machines
Carapace	Better completions	You use many CLI tools and want smarter TAB completions

Recommended: Start with FZF (most universally useful), then add Atuin if you like the enhanced history search.

---

What You'll Get

✅ Ghostty terminal with Night Owl theme
✅ JetBrains Mono Nerd Font with icons
✅ Starship gradient prompt with git/language info
✅ Zsh with syntax highlighting + autosuggestions
✅ Vi-mode keybindings (jk escape, Ctrl+L accept)
✅ Split pane keybindings (Super/Ctrl+Shift+hjkl)

---

Troubleshooting

Fonts not showing icons

• Ensure you've installed a Nerd Font and set it in Ghostty config
• Restart Ghostty after font installation

Starship not displaying

• Verify eval "$(starship init zsh)" is in your .zshrc
• Run source ~/.zshrc to reload

Plugins not working

• Ensure plugins are installed in ~/.oh-my-zsh/custom/plugins/
• Check that they're listed in the plugins=() array in .zshrc

---

File Structure

~/.config/
├── ghostty/
│   ├── config
│   └── themes/
│       ├── night-owl
│       ├── everforest-light
│       └── noctis-azureus
└── starship.toml

~/.zshrc

---

License

MIT