zshrc Customization for a More Comfortable Daily Terminal Experience

Never Lose Your Way Even After Changing PCs: The Ultimate .zshrc Built with fzf × ghq × Oh My Zsh

This is a personal memo for those times I think, "Wait, how did I do this before?" every time I buy a new PC.

Do you have these kinds of frustrations in your daily development?

• Switching Git branches is tedious
• It takes time to find a repository you cloned locally
• The terminal looks plain, and it doesn't get you excited
• You execute commands without noticing typos

In this article, we will build a "Fast, Readable, and Intuitive" terminal environment by combining the following tools:

• fzf
• ghq
• Oh My Zsh
• zsh-autosuggestions
• zsh-syntax-highlighting

The resulting .zshrc is configured so that you can simply copy and paste it.

---

Overall Design Philosophy

The philosophy behind this setup is very simple.

ghq      → Centralized management of GitHub repositories
  ↓
fzf      → Interactive search & selection
  ↓
Zsh functions  → cd / checkout / code
  ↓
Oh My Zsh → Completion, prompt, and appearance

• Don't remember where you cloned
• Don't memorize branch names
• Decide visually

Just these principles will drastically reduce terminal stress.

---

Required Packages

First, install the base tools.

brew install ghq fzf zsh-autosuggestions zsh-syntax-highlighting

Roles of Each Tool

Tool	Role
ghq	Centrally manages GitHub repositories locally
fzf	Blazing fast interactive search
zsh-autosuggestions	History-based auto-completion
zsh-syntax-highlighting	Color coding of commands while typing

---

Initial Setup for ghq

Specify the root directory to be managed by ghq.

git config --global ghq.root '~/ghq'

Now, cloned repositories will be organized as follows:

~/ghq/github.com/username/repository

The "Where did I clone that?" problem completely disappears.

---

How to Apply .zshrc

# Open with VSCode
code ~/.zshrc

# Apply settings
source ~/.zshrc

---

Complete .zshrc

Below is the final version.

.zshrc

# ============================================================
# Oh My Zsh
# ============================================================

## @doc Specifies the installation directory for Oh My Zsh.
export ZSH="$HOME/.oh-my-zsh"

## @doc Specifies the prompt theme (agnoster).
ZSH_THEME="agnoster"

## @doc List of Oh My Zsh plugins to load.
##      This configuration is aimed at daily CLI operations, completion, and productivity improvements.
plugins=(
  git                  # Git aliases & completion
  z                    # Rapidly navigate to frequently used directories
  fzf                  # fzf integration
  docker               # Docker command completion
  docker-compose       # Docker Compose completion
  node                 # Node.js completion
  npm                  # npm completion
  pnpm                 # pnpm completion
  yarn                 # yarn completion
  brew                 # Homebrew completion
  vscode               # VSCode integration
  zsh-autosuggestions  # History-based auto-completion
  copypath             # Copy current directory path to clipboard
  you-should-use       # Suggests aliases for commands you use
  aliases              # Collection of useful aliases
)

## @doc Loads Oh My Zsh.
source "$ZSH/oh-my-zsh.sh"

## @doc Loads fzf keybindings and completion settings for Zsh.
##      Officially recommended initialization method assuming fzf is managed by Homebrew.
source <(fzf --zsh)


# ============================================================
# Prompt Customization (agnoster)
# ============================================================

# ------------------------------------------------------------
# Prompt Segment Color Tuning
# ------------------------------------------------------------

prompt_context() {
  prompt_segment black default "endotakumi"
}

## @doc Overwrites the definition of agnoster's directory segment.
##      Keeps the displayed content (full path) as is, but tones down the background color.
##      Prioritizes visibility even when paths include Japanese characters.
prompt_dir() {
  local dir="${PWD/#$HOME/~}"
  prompt_segment blue white "$dir"
}

# ------------------------------------------------------------
# Git Prompt Color Tuning
# ------------------------------------------------------------

## @doc Adjusts agnoster's Git status colors to a calmer palette.
##      Tones down clean/dirty/conflict indicators to improve readability.
ZSH_THEME_GIT_PROMPT_CLEAN="%{$fg[cyan]%}"
ZSH_THEME_GIT_PROMPT_DIRTY="%{$fg[yellow]%}"
ZSH_THEME_GIT_PROMPT_UNTRACKED="%{$fg[red]%}"
ZSH_THEME_GIT_PROMPT_CONFLICTS="%{$fg[red]%}"

## @doc Sets the Git branch name color slightly darker.
##      Aimed at adjusting the contrast with the background color.
ZSH_THEME_GIT_PROMPT_BRANCH="%{$fg[blue]%}"

# ============================================================
# Prompt Newline
# ============================================================

## @doc Configures the prompt display in a two-line format: "info line + input line".
##      Adds a newline to the end of the PROMPT generated by the agnoster theme,
##      moving the command input field to the next line.
##      Existing agnoster segment displays are maintained.
PROMPT="${PROMPT}"$'\n> '


# ============================================================
# Syntax Highlighting
# ============================================================

## @doc Loads zsh-syntax-highlighting from common Homebrew paths.
##      Supports both Apple Silicon and Intel (sources whichever exists).
if [ -f /opt/homebrew/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh ]; then
  source /opt/homebrew/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh
elif [ -f /usr/local/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh ]; then
  source /usr/local/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh
fi


# ============================================================
# Environment
# ============================================================

## @doc Specifies the default editor.
export EDITOR="vim"

## @doc Specifies the default browser.
export BROWSER="google-chrome"

## @doc Specifies the locale.
export LANG="ja_JP.UTF-8"


# ============================================================
# PATH
# ============================================================

## @doc Adds the user's binary directory to the PATH.
export PATH="$HOME/.local/bin:$PATH"

## @doc Adds /usr/local/bin to the PATH (for Intel Macs or manual placement).
export PATH="/usr/local/bin:$PATH"


# ============================================================
# Functions
# ============================================================

## @doc Selects a local Git branch with fzf and checks it out.
## @param $1 Option: Specify "-simple" to simplify the log display.
sw() {
  if [ "$1" = "-simple" ]; then
    git branch --format="%(refname:short)" |
      fzf --preview='git log --pretty=format:"%h %cd %s" --date=format:"%Y-%m-%d %H:%M " {}' \
          --preview-window=right:70%:wrap \
          --ansi |
      xargs git checkout
  else
    git branch --format="%(refname:short)" |
      fzf --preview='git log --graph --oneline --decorate --color=always {}' \
          --preview-window=right:70%:wrap \
          --ansi |
      xargs git checkout
  fi
}

## @doc Selects a repository managed by ghq with fzf and moves to that directory.
cdrepo() {
  local repodir
  repodir=$(ghq list | fzf -1 +m) || return 1
  cd "$(ghq root)/$repodir" || return 1
}

## @doc Selects a repository managed by ghq with fzf and opens it in VSCode.
coderepo() {
  local repodir
  repodir=$(ghq list | fzf -1 +m) || return 1
  echo "Open VSCode Workspace! : $(ghq root)/$repodir"
  code "$(ghq root)/$repodir"
}


# ============================================================
# Aliases
# ============================================================

## @doc Saves all changes as a temporary commit (WIP).
##      Intended for snapshots during work-in-progress.
alias gwip='git add -A && git commit -m "[WIP]"'


# ============================================================
# Notes / Install Memo
# ============================================================

## @doc Installation memo for the zsh-you-should-use plugin (instructions, not settings).
##      Clone into the Oh My Zsh custom plugin directory before adding to plugins.
##      * This block is a memo intended as comments (not to be executed by the shell).
#
# -----
#
# oh-my-zsh
#
# Clone this repository using the following command:
#
# git clone https://github.com/MichaelAquilina/zsh-you-should-use.git \
#   ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/you-should-use
#
# -----
#
# pnpm
#
# Clone this repository using the following command:
#
# git clone --depth=1 https://github.com/ntnyq/omz-plugin-pnpm.git \
#   ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/pnpm
#
# -----
#
# zsh-autosuggestions
#
# Clone this repository using the following command:
#
# git clone https://github.com/zsh-users/zsh-autosuggestions \
#   ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions
#

export BROWSER="open -a 'Google Chrome'"

---

Custom Command Explanation

Git Branch Switching (sw)

sw

• Displays the branch list using fzf
• Previews the commit graph on the right side
• Checkout while verifying the status

The "I don't know which branch is the newest" problem disappears.

---

Repository Navigation (cdrepo / coderepo)

cdrepo
coderepo

• Type a few characters → Navigate instantly
• Launch VSCode in just one step

The cognitive cost of searching for repositories is reduced to zero.

---

Temporary Commit (gwip)

gwip

• Stashing work-in-progress
• Before switching branches
• Safety net before pulling

Convenient whenever you just want to "save the current state."

---

Visual Design Tweaks

• Tone down the color scheme based on the agnoster theme
• Configure the prompt into a two-line layout

~/project (git:main)
> _

The input position remains constant, making it easier to stay focused.

---

Why This Configuration is So Comfortable

• No need to memorize
• No need to search
• Can decide visually
• Complete everything using only the keyboard

Since .zshrc is a "tool you use every day," small improvements lead to significant time savings.

---

Conclusion

Once you use the combination of fzf × ghq × Oh My Zsh, you can't go back.

Even if you change your PC, just restoring your .zshrc makes you ready for action immediately.

I highly recommend this to anyone who wants to reduce terminal stress 🚀