ZSH Configuration

A modular, modern ZSH configuration with security-first defaults, lazy loading, and cross-platform support.

Features

Feature	Description
Modular Architecture	Enable/disable features independently via Z_*_ENABLED flags
Lazy Loading	Deferred initialization for starship, atuin, zoxide, nvm, pyenv, rbenv
Security First	History filtering, safe aliases, ownership verification
Cross-Platform	macOS (Intel/Apple Silicon) and Linux with auto-detection
XDG Compliant	Respects XDG Base Directory specification
Performance	Caching, optional compilation, minimal SSH mode

Quick Start

# Option 1: Clone and install (recommended)
git clone https://github.com/chiptoma/dotfiles-zsh ~/.config/zsh
~/.config/zsh/install.sh

# Option 2: One-liner via curl
curl -fsSL https://raw.githubusercontent.com/chiptoma/dotfiles-zsh/main/install.sh | bash

The installer automatically:

• Installs Oh My Zsh if missing
• Configures ZDOTDIR
• Creates XDG directories
• Installs essential tools (starship prompt, atuin history)
• Offers recommended tool installation (fzf, eza, zoxide, etc.)

See INSTALL.md for detailed instructions.

Architecture

~/.config/zsh/
├── .zshenv                 # Entry point: XDG, logging, utils, platform, path
├── .zshrc                  # Interactive: plugins, modules, keybindings
├── .zshlocal               # User customizations (gitignored)
│
├── modules/
│   ├── logging.zsh         # Log levels, colors, caller info
│   ├── environment.zsh     # ENV vars, XDG dirs, editor detection
│   ├── path.zsh            # PATH management, platform paths
│   ├── lazy.zsh            # Deferred tool initialization
│   ├── completion.zsh      # Tab completion, caching
│   ├── history.zsh         # History management, security filtering
│   ├── aliases.zsh         # Command aliases, modern replacements
│   ├── keybindings.zsh     # Key bindings, atuin/fzf integration
│   └── compilation.zsh     # Optional .zwc compilation
│
├── lib/
│   ├── utils.zsh           # Core utilities (_has_cmd, _safe_source, etc.)
│   ├── platform/
│   │   ├── macos.zsh       # macOS-specific (Homebrew, app bundles)
│   │   └── linux.zsh       # Linux-specific (snap, flatpak)
│   └── functions/
│       ├── index.zsh       # Auto-discovery barrel
│       ├── system.zsh      # calc, weather, sysinfo
│       ├── file.zsh        # File operations
│       ├── git.zsh         # Git helpers
│       ├── docker.zsh      # Docker/container helpers
│       ├── network.zsh     # Network utilities
│       ├── python.zsh      # Python/venv helpers
│       └── introspection.zsh  # Shell debugging
│
└── completions/            # Custom completions

Documentation

Detailed documentation for each module:

Interactive Modules

Module	Docs	Description
History	docs/history.md	Security filtering, interactive search, statistics
Aliases	docs/aliases.md	200+ aliases organized by category
Functions	docs/functions.md	30+ utility functions (calc, weather, ports, etc.)
Keybindings	docs/keybindings.md	Atuin, navigation, editing shortcuts
Completion	docs/completion.md	Smart tab completion with caching

Core Infrastructure

Module	Docs	Description
PATH	docs/path.md	Intelligent PATH with 50+ dev tools
Environment	docs/environment.md	XDG compliance, editor detection
Lazy Loading	docs/lazy.md	Deferred init for fast startup
Platform	docs/platform.md	macOS/Linux detection and helpers
Logging	docs/logging.md	Debug levels, colors, caller info
Utils	docs/utils.md	Core helpers (_has_cmd, _cache_eval)
Compilation	docs/compilation.md	Optional .zwc bytecode compilation

Modules

Essential (Always Load)

Module	Docs	Purpose
Logging	docs/logging.md	_log function with levels, colors, caller info
Utils	docs/utils.md	Core helpers: _has_cmd, _safe_source, _cache_eval
Platform	docs/platform.md	OS-specific detection and paths
Functions	docs/functions.md	User-facing z_* functions

Optional (Toggleable)

Module	Docs	Default	Purpose
Environment	docs/environment.md	enabled	XDG dirs, editor detection, tool configs
Path	docs/path.md	enabled	PATH management, dev tools, version managers
Lazy	docs/lazy.md	enabled	Deferred init for slow tools
Completion	docs/completion.md	enabled	Tab completion with caching
History	docs/history.md	enabled	History with security filtering
Aliases	docs/aliases.md	enabled	Modern tool replacements
Keybindings	docs/keybindings.md	enabled	Key bindings (atuin, navigation)
Compilation	docs/compilation.md	disabled	.zwc bytecode compilation

Configuration Reference

All options can be set in .zshlocal or exported before sourcing.

Global

Variable	Default	Description
Z_LOG_LEVEL	WARN	Log verbosity: DEBUG, INFO, WARN, ERROR, NONE

Module Toggles

Variable	Default	Description
Z_ENVIRONMENT_ENABLED	true	Environment module
Z_PATH_ENABLED	true	PATH module
Z_LAZY_ENABLED	true	Lazy loading module
Z_COMPLETION_ENABLED	true	Completion module
Z_HISTORY_ENABLED	true	History module
Z_ALIASES_ENABLED	true	Aliases module
Z_KEYBINDINGS_ENABLED	true	Keybindings module
Z_COMPILATION_ENABLED	false	Compilation module

Lazy Loading

Variable	Default	Description
Z_LAZY_ZOXIDE	true	Lazy load zoxide
Z_LAZY_NVM	true	Lazy load nvm
Z_LAZY_PYENV	true	Lazy load pyenv
Z_LAZY_RBENV	true	Lazy load rbenv

Environment

Variable	Default	Description
Z_ENVIRONMENT_XDG_STRICT	true	Enforce XDG for all tools
Z_ENVIRONMENT_SSH_MINIMAL	true	Minimal env in SSH sessions
Z_ENVIRONMENT_SSH_AGENT	true	Auto-detect SSH agent socket
Z_LOCALE_OVERRIDE	empty	Override system locale
Z_GUI_EDITORS_ORDER	"surf cursor code"	GUI editor preference
Z_TERMINAL_EDITORS_ORDER	"nvim vim vi"	Terminal editor preference

PATH

Variable	Default	Description
Z_PATH_HOMEBREW	true	Detect and init Homebrew
Z_PATH_CLEAN	true	Remove non-existent dirs
Z_PATH_PROJECT_BIN	false	Add ./bin, ./node_modules/.bin
Z_PATH_SSH_MINIMAL	true	Minimal PATH in SSH
Z_PATH_FORCE_MINIMAL	false	Force minimal PATH always

History

Variable	Default	Description
Z_HISTORY_SIZE	100000	Commands in memory
Z_HISTORY_SAVE_SIZE	100000	Commands saved to file
Z_HISTORY_SECURITY_FILTER	true	Filter sensitive commands

Completion

Variable	Default	Description
Z_COMPLETION_TTL	86400	Compdump TTL in seconds (24h)
Z_COMPLETION_MENU_SELECT	true	Arrow-key menu selection

Aliases

Variable	Default	Description
Z_ALIASES_MODERN_TOOLS	true	Use eza, bat, ripgrep, etc.
Z_ALIASES_SAFETY_PROMPTS	true	Confirm destructive ops

Compilation

Variable	Default	Description
Z_COMPILATION_CLEANUP_ON_START	true	Clean stale .zwc on startup

Update Check

Variable	Default	Description
Z_UPDATE_CHECK_ENABLED	true	Check for updates on shell launch
Z_UPDATE_CHECK_INTERVAL	86400	Seconds between checks (24h)
Z_UPDATE_AUTO_FETCH	true	Fetch updates in background

Other

Variable	Default	Description
Z_VERIFY_FILE_OWNERSHIP	false	Check file ownership before sourcing

Customization

Create .zshlocal (gitignored) for personal settings:

cp examples/zshlocal .zshlocal
$EDITOR .zshlocal

Example customizations:

# Directory shortcuts
alias dev='cd ~/Development'
alias prj='cd ~/Projects'

# Enable project-local binaries
export Z_PATH_PROJECT_BIN=true

# Override locale
export Z_LOCALE_OVERRIDE="en_US.UTF-8"

# Debug mode (see all module loading)
export Z_LOG_LEVEL=DEBUG

# Disable lazy loading for specific tools
export Z_LAZY_ZOXIDE=false

Key Bindings

Key	Action
Up/Down	Atuin history search (if installed)
Ctrl-R	Interactive history search
Alt-Up/Down	Directory history navigation
Ctrl-Backspace	Delete word backward
Home/End	Beginning/end of line

Useful Commands

Shell Introspection

Alias	Command	Description
lazy	z_lazy_status	Show lazy loading status
zupdate	z_update	Update to latest version
zversion	z_version	Show current version
path	path_show	Display PATH entries
pathdebug	path_debug	PATH diagnostics
hstats	history_stats	Top commands chart
als	z_alias_browser	Interactive alias browser (fzf)

Popular Aliases (see docs/aliases.md for 200+)

Alias	Expansion	Category
gs	git status --short --branch	Git
gaa	git add --all	Git
gcm	git commit -m	Git
gps	git push	Git
.. / ...	cd .. / cd ../..	Navigation
mkcd	Create dir and cd into it	Navigation
lt	eza --tree --level=2 --icons	Modern tools
G	| grep (global alias)	Piping

Troubleshooting

Commands not found after install:

exec zsh  # Restart shell completely

Debug module loading:

export Z_LOG_LEVEL=DEBUG
exec zsh

Check lazy loading status:

z_lazy_status

PATH issues:

pathdebug      # Show diagnostics
pathclean      # Remove non-existent entries

Reset completion cache:

rm -f ~/.cache/zsh/completion/zcompdump*
exec zsh

Dependencies

Required:

• ZSH 5.8+
• Oh My Zsh

Essential (installed automatically):

• starship - Cross-shell prompt with git status
• atuin - Shell history search and sync

Recommended (prompted during install):

• fzf - Fuzzy finder (Ctrl+R, Ctrl+T)
• zoxide - Smarter cd
• eza - Modern ls with icons
• bat - Modern cat with syntax highlighting
• ripgrep - Fast grep
• fd - Modern find

# macOS
brew install starship atuin fzf zoxide eza bat ripgrep fd

# Linux (Ubuntu/Debian) - see INSTALL.md for details
# Note: bat→batcat, fd→fdfind on Debian-based systems

License

MIT