ZSHAND — Project Summary¶

ZSHAND is a high-performance Zsh framework that replaces the traditional monolithic .zshrc with a modular, compiled, cross-platform shell configuration. Instead of maintaining one enormous config file, you organize your shell setup into purpose-specific directories, and the framework compiles everything into optimized bytecode bundles for fast loading.

Architecture¶

The framework entry point is zshrc.zsh, which orchestrates the entire initialization sequence. It loads 11 core modules (variables, PATH, engine, audit, options, completions, aliases, widgets, hooks, plugins, and functions) in a strict numeric order. On top of core, there are 26 user-facing shell functions for tasks like health checks, archive extraction, git utilities, and file transfers. Twenty ZLE widgets provide lazy-loaded keyboard shortcuts for smart paste, AI-powered commit messages, fzf-based file and branch pickers, clipboard history, and JSON formatting. Nine hook scripts integrate external tools like Mise, Atuin, SSH agent, Docker, and Zoxide. Fifteen startup scripts handle bootstrapping concerns such as dev mode detection, Wayland clipboard, TOML config loading, and safe mode recovery. Around 30 standalone CLI tools in bin/ cover rebuilding (zr), quick-editing (ze, zd), health checking (health), file transfer (pcopy, persync), and profiling (zprofile). Platform installers exist for Debian, Ubuntu, Manjaro, macOS, and WSL.

User configuration lives in ~/.config/zshand/ following the XDG Base Directory specification. This includes aliases, environment variables, secrets, custom functions, widgets, hooks, and numbered rc.d/ overrides. Framework updates never touch user files.

Loading Modes¶

The framework supports five loading strategies. Full bundle mode compiles everything — framework and user config — into a single file for the fastest possible startup (~42ms). Monolithic mode loads a framework-only bundle. Hybrid mode uses per-directory compiled bundles in production and falls back to individual files in development. Individual mode loads every file separately for debugging (~180ms). Profile mode instruments loading with timing data for performance analysis. Setting ZSHAND_AUTO_FULL=1 in ~/.zshenv enables automatic bundle compilation on first run and fast-path loading on subsequent sessions.

Safety and Recovery¶

If the shell detects repeated initialization failures, it automatically enters safe mode — a minimal recovery environment that bypasses the full framework. Users can also force safe mode with ZSHAND_SAFE_MODE=1. Dev mode (ZSHAND_DEV_MODE=1) enables detailed per-file timing output and disables bundle loading for debugging.

Technology Stack¶

ZSHAND targets Zsh 5.9+ and uses zcompile for bytecode compilation. The default theme is Powerlevel10k with instant prompt support for zero-latency rendering. Shell enhancements include zsh-autosuggestions and zsh-syntax-highlighting. History is managed by Atuin (encrypted and synced across machines). Navigation uses Zoxide with fzf for fuzzy directory jumping. File listings use Eza with icons and git status integration. Linting is handled by Trunk (wrapping ShellCheck and shfmt). Documentation is built with MkDocs Material. CI runs on GitHub Actions with a lint/test/benchmark matrix, and releases are automated via Release Please.

Performance¶

Production startup with the full bundle takes approximately 42ms on the reference machine. Hybrid mode with per-directory bundles runs around 80ms. Individual file loading in dev mode takes about 180ms. The CI pipeline fails the build if startup time regresses by more than 10ms from the baseline.

Daily Workflow¶

The typical workflow is: edit a config file with ze aliases or ze functions, rebuild with zr, and open a new terminal. zupdate pulls remote changes, rebuilds, and runs a health check — think of it as apt update for your shell. health runs a comprehensive diagnostic verifying syntax, compiled cache freshness, dependencies, and PATH integrity. ZSHAND_DEBUG=1 exec zsh restarts the shell with full timing diagnostics. Optional JSONL telemetry, session logs, and logstat analytics provide long-term usage insights.

Scale¶

The project contains approximately 199 .zsh source files, 30 bin scripts, 11 test suites, and over 15 documentation pages. It is a single-developer project (Andrew), MIT licensed, currently at version 0.1.0.