Zsh Shell Setup and Configuration for Salchipapa.Dots

Zsh is the alternative shell option in Salchipapa.Dots. It is built on top of Oh My Zsh with the nanotech theme and enriched by Homebrew-installed plugins for syntax highlighting, autosuggestions, and tab completions via Carapace. Like the Fish configuration, it auto-starts Zellij on every interactive session, giving you an identical multiplexed workflow regardless of which shell you choose.

Setup

The Zsh configuration is a single .zshrc file symlinked into your home directory by the installer. To link it manually:

ln -s ~/Salchipapa.Dots/SalchipapaZsh/.zshrc ~/.zshrc

The installer (sudo ./install.sh) handles this symlink automatically when you select Zsh as your shell. You do not need to run this command if you used the installer.

Oh My Zsh

Oh My Zsh is the framework that loads the theme and plugins. The theme is set to nanotech:

export ZSH="$HOME/.oh-my-zsh"
ZSH_THEME="nanotech"

The only plugin loaded through Oh My Zsh’s built-in plugin system is command-not-found, which suggests the package to install when an unknown command is entered:

plugins=(
  command-not-found
)

source $ZSH/oh-my-zsh.sh

Homebrew Plugins

Three additional Zsh plugins are sourced directly from Homebrew’s share directory. The correct Homebrew prefix is detected automatically based on the OS:

if [[ "$(uname)" == "Darwin" ]]; then
    BREW_BIN="/opt/homebrew/bin"
else
    BREW_BIN="/home/linuxbrew/.linuxbrew/bin"
fi

eval "$($BREW_BIN/brew shellenv)"

source $(dirname $BREW_BIN)/share/zsh-autocomplete/zsh-autocomplete.plugin.zsh
source $(dirname $BREW_BIN)/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh
source $(dirname $BREW_BIN)/share/zsh-autosuggestions/zsh-autosuggestions.zsh

Plugin	Description
`zsh-autocomplete`	Real-time completion menu that appears as you type, without pressing Tab
`zsh-syntax-highlighting`	Highlights valid commands in green and invalid ones in red while you type
`zsh-autosuggestions`	Grays out history-based command completions; press `→` to accept

BREW_BIN switches between /opt/homebrew/bin (macOS) and /home/linuxbrew/.linuxbrew/bin (Linux) based on the output of uname, so the same .zshrc works on both platforms without modification.

NVM Setup

Node Version Manager is loaded via the Homebrew-managed NVM formula. Both the NVM shell integration and bash completion are sourced:

export NVM_DIR="$HOME/.nvm"
[ -s "/home/linuxbrew/.linuxbrew/opt/nvm/nvm.sh" ] && \. "/home/linuxbrew/.linuxbrew/opt/nvm/nvm.sh"
[ -s "/home/linuxbrew/.linuxbrew/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/home/linuxbrew/.linuxbrew/opt/nvm/etc/bash_completion.d/nvm"

Carapace Completions

Carapace provides completion bridging across multiple shell environments. The bridge list and the completion style are configured before the Carapace source command:

export CARAPACE_BRIDGES='zsh,fish,bash,inshellisense'
zstyle ':completion:*' format $'\e[2;37mCompleting %d\e[m'
source <(carapace _carapace)

The zstyle line styles completion category headers with a dimmed grey label so they are easy to scan visually.

Tool Initializations

After Oh My Zsh and plugins are loaded, the major CLI integrations are initialized:

eval "$(fzf --zsh)"
eval "$(zoxide init zsh)"
eval "$(atuin init zsh)"

fzf

Fuzzy finder — adds key bindings for history search (Ctrl+R), file search (Ctrl+T), and directory navigation (Alt+C).

Zoxide

Smarter cd replacement. Tracks visit frequency and lets you jump to directories with z <name>. The cd alias also maps to z directly.

Atuin

Replaces shell history with a searchable SQLite database. Supports encrypted sync across machines.

Angular CLI Completion

Angular CLI completions are loaded automatically at the end of .zshrc:

source <(ng completion script)

This adds Tab completion for all ng subcommands, flags, and project-specific schematics.

Aliases

Listing Aliases

All listing aliases use eza as a modern replacement for ls, with Nerd Font icons and Git integration.

Alias	Command	Description
`ls`	`eza --no-permissions --git --no-time --no-user --icons --group-directories-first`	Clean listing with icons, directories first
`ll`	`eza -l --no-permissions -no-time --no-user --icons --group-directories-first`	Long listing without permission/time/user columns
`la`	`eza -la --no-permissions --no-time --no-user --icons --group-directories-first`	Long listing including hidden files
`lt`	`eza -lT --no-permissions --no-time --no-user --icons --group-directories-first`	Full tree view
`lt2`	`eza -lT --no-permissions --no-time --no-user --icons --group-directories-first --level=2`	Tree — 2 levels deep
`lt3`	`eza -lT --no-permissions --no-time --no-user --icons --group-directories-first --level=3`	Tree — 3 levels deep
`lt4`	`eza -lT --no-permissions --no-time --no-user --icons --group-directories-first --level=4`	Tree — 4 levels deep
`lS`	`eza -l --no-permissions --sort=size --icons`	Sorted by file size
`lD`	`eza -l --no-permissions --sort=date --icons`	Sorted by modification date
`lg`	`eza -l --no-permissions --git --icons`	Long listing with Git status column
`lf`	`eza -l --git --group-directories-first`	Long listing with permissions and Git info

Git Aliases

Alias	Command	Description
`gs`	`git status`	Show working tree status
`ga`	`git add`	Stage changes
`gc`	`git commit -m`	Commit with inline message
`gp`	`git push -u origin main`	Push and set upstream to `main`

Alias	Command	Description
`cd`	`z`	Replace `cd` with zoxide for smart directory jumping

Fuzzy Finder Aliases

Alias	Command	Description
`fzfbat`	`fzf --preview="bat --theme=gruvbox-dark --color=always {}"`	fzf with Gruvbox-themed bat preview
`fzfnvim`	`nvim $(fzf --preview="bat --theme=gruvbox-dark --color=always {}")`	Open fzf selection in Neovim

Zellij Auto-Start

Zellij is launched at the end of .zshrc by calling start_if_needed. The function checks that the session is interactive, that Zellij is not already running, and that stdout is a real terminal before executing:

WM_VAR="/$ZELLIJ"
WM_CMD="zellij"

function start_if_needed() {
    if [[ $- == *i* ]] && [[ -z "${WM_VAR#/}" ]] && [[ -t 1 ]]; then
        exec $WM_CMD
    fi
}

# ... rest of .zshrc ...

start_if_needed

WM_VAR="/$ZELLIJ" — Zellij sets $ZELLIJ to a non-empty value when already running. The leading / means ${WM_VAR#/} strips it and returns the session ID; an empty result means Zellij is not active.
WM_CMD="zellij" — the command to execute. Update this variable to switch to a different multiplexer without changing the function logic.

To swap Zellij for Tmux, change WM_VAR="/$TMUX" and WM_CMD="tmux". The start_if_needed function logic stays identical.

WSL Runtime Directory Fix

Zellij requires a valid XDG_RUNTIME_DIR. In WSL this directory does not exist by default, which causes Zellij to fail at startup. The .zshrc creates and secures it automatically:

export XDG_RUNTIME_DIR="/tmp/zellij-$UID"
mkdir -p "$XDG_RUNTIME_DIR"
chmod 700 "$XDG_RUNTIME_DIR"

This runs on every shell start, which is safe because mkdir -p is a no-op if the directory already exists.

/tmp is cleared on reboot in most Linux systems. The directory will be re-created automatically on the next shell start, so this is expected behavior rather than a bug.

PATH

PATH is extended with Volta and Cargo binaries near the top of .zshrc, before any tool initialization:

export PATH="$HOME/.volta/bin:$HOME/.cargo/bin:$PATH"

Entry	Purpose
`$HOME/.volta/bin`	Volta — manages Node.js, npm, and Yarn versions without requiring `nvm use`
`$HOME/.cargo/bin`	Rust binaries installed via `cargo install` (e.g., `eza`, `bat`, `fd`, `zoxide`)

Shell Options

Two setopt directives tune Zsh’s interactive behavior:

setopt autocd   # Type a directory name to cd into it without writing `cd`
setopt correct  # Suggest corrections for mistyped commands

FZF Environment Variables

Default FZF commands are configured to use fd for fast, .git-excluding file discovery:

export FZF_DEFAULT_COMMAND="fd --hidden --strip-cwd-prefix --exclude .git"
export FZF_DEFAULT_T_COMMAND="$FZF_DEFAULT_COMMAND"
export FZF_ALT_COMMAND="fd --type=d --hidden --strip-cwd-prefix --exlude .git"

These ensure that fzf’s file picker (Ctrl+T) and directory picker (Alt+C) are both fast and respect .gitignore-style exclusions.

Get Started

Shell

Terminal & Multiplexer

Neovim

Tools & Integrations

Zsh Shell Setup and Configuration for Salchipapa.Dots

Setup

Oh My Zsh

Homebrew Plugins

NVM Setup

Carapace Completions

Tool Initializations

fzf

Zoxide

Atuin

Angular CLI Completion

Aliases

Listing Aliases

Git Aliases

Navigation Aliases

Fuzzy Finder Aliases

Zellij Auto-Start

WSL Runtime Directory Fix

PATH

Shell Options

FZF Environment Variables

Build docs developers (and LLMs) love

Get Started

Shell

Terminal & Multiplexer

Neovim

Tools & Integrations

Documentation Index

​Setup

​Oh My Zsh

​Homebrew Plugins

​NVM Setup

​Carapace Completions

​Tool Initializations

fzf

Zoxide

Atuin

​Angular CLI Completion

​Aliases

​Listing Aliases

​Git Aliases

​Navigation Aliases

​Fuzzy Finder Aliases

​Zellij Auto-Start

​WSL Runtime Directory Fix

​PATH

​Shell Options

​FZF Environment Variables

Build docs developers (and LLMs) love

Setup

Oh My Zsh

Homebrew Plugins

NVM Setup

Carapace Completions

Tool Initializations

Angular CLI Completion

Aliases

Listing Aliases

Git Aliases

Navigation Aliases

Fuzzy Finder Aliases

Zellij Auto-Start

WSL Runtime Directory Fix

PATH

Shell Options

FZF Environment Variables