Skip to content

ZSHANDΒΆ

High-performance Zsh framework for developers who don't wait.
OMZ plugins Β· ZSHAND plugins Β· widgets Β· hooks β€” fast or deferred.
Override anything. Have your .zshrc and source it too.

v2.0.0 <50ms cold start Beta
Quick Start GitHub
~
❯ health
βœ“ startup  <50ms  Β· 11 modules Β· 10 hooks deferred
βœ“ widgets  20 bound  Β· lazy stubs Β· 1ms each
βœ“ bundle   1 .zwc  Β· 100+ files compiled
βœ“ tools    70+ installed  Β· pkgsync verified

❯ zr
βœ“ recompiled in ~1s

❯ zprofile --report
  1. 12ms  hooks/01_mise.zsh
  2.  8ms  core/20_plugins.zsh
  3.  4ms  core/18_hooks.zsh

⚑ Why ZSHAND?¢

Love OMZ? β€” Import its plugins and completions, lose the 300ms startup. One command: import-ohmyzsh-plugins. β†’ Import Guide
Love P10k? β€” Built in. Plus 20+ widgets, 10 hooks, aliases, functions, and a full compile pipeline. β†’ Widgets & Hooks
Your code = first class β€” Plugins profiled, compiled to .zwc bytecode, inlined with the framework. Same treatment as core. β†’ Your Config

  • <50ms Cold Start

    P10k instant prompt + compiled .zwc bytecode. 100+ source files β†’ 1 bundle via zmono. Your config compiled in too via zfull.

    Performance

  • Import OMZ / P10k / Prezto

    One command each: import-ohmyzsh-plugins, import-p10k-theme, import-prezto-themes. Bring your setup β€” don't start over.

    CLI Tools

  • Override Without Forking

    Drop 05_my_module.zsh in rc.d/ β€” it loads between 04_path and 06_engine. Override any core module, widget, hook, or function. Zero patching, zero forks.

    Config

  • Self-Healing Shell

    3 failures β†’ Safe Mode auto-triggers: recovery menu, minimal PATH, one-command fixes. health + ztop dashboards. PATH auto-heals.

    Safe Mode

  • Auto System Setup

    packages.toml declares every tool, language, and app. Fresh machine? One cloner.sh run installs 70+ tools, sets up SSH/GPG, and compiles the framework. pkgsync keeps it all in sync.

    Packages

  • 20+ Keyboard Widgets

    AI commit (Ctrl+B), fuzzy file picker (Ctrl+T), man page search (Alt+M), git branch picker, and more β€” all lazy-loaded, compile on first keypress.

    Widgets

  • Auto-Generated Docs

    Every file has structured headers. docgen generates source docs + Mermaid dependency graphs from framework and your files. aicontext exports for Cursor/Windsurf/Claude.

    Source Reference

  • AI-Native Workflow

    aicmit generates commits from diffs. aidebug builds error-diagnosis prompts. pastem smart-pastes AI responses. Project manifests via aicontext.

    Widgets

πŸ”© Under the HoodΒΆ

Everything above is powered by a 5-layer architecture β€” from your user config down to bytecode. Each layer is numbered, overridable, and compiled into a single .zwc bundle.
ZSHAND Architecture

Architecture Core Modules Startup Pipeline

πŸš€ Quick StartΒΆ

  • Setup

    1. Clone & bootstrap β€” detects your OS, installs 70+ tools, sets up SSH/GPG keys, writes shell profiles, and compiles the framework:

    bash <(curl -fsSL https://raw.githubusercontent.com/presempathy/zshand/main/cloner.sh)

    Supports Debian, Manjaro, macOS, WSL. Flags: --dry-run, --update, --uninstall.

    2. First run β€” interactive setup wizard:

    exec zsh              # restart into ZSHAND
setup.zsh             # guided setup: git identity, secrets, theme

    3. Choose your mode β€” pick how ZSHAND runs:

    ~/.config/zshand/config.toml
    [framework]
# Fast mode (default) β€” compiled bytecode
dev_mode = false
auto_full = true      # auto-recompile on changes
perf_budget = 5       # warn if any file > 5ms

# Dev mode β€” raw source, instant edits
# dev_mode = true

    4. Secrets β€” auto-secured with chmod 600 every startup:

    ~/.config/zshand/secrets.zsh
    export OPENAI_API_KEY="sk-..."
export GITHUB_TOKEN="ghp_..."

  • Basic Usage

    After install β€” verify and start using:

    exec zsh              # restart β€” ZSHAND is now active
health                # verify everything works

    Compile β€” run after any edit:

    zr                    # quick recompile (~1s)
zfull                 # framework + your config (~3s)
zfresh                # clean rebuild + restart (~4s)
zupdate               # full maintenance cycle

    Profile β€” find what's slow:

    zprofile              # instrumented profiling
zprofile --report     # last timing report
ztop                  # live framework dashboard

    Import β€” bring your existing setup:

    import-ohmyzsh-plugins  # OMZ plugins β†’ ZSHAND
import-p10k-theme       # your .p10k.zsh config
import-prezto-themes    # Prezto themes

    Just recipes β€” just --list for all:

    just docs-preview     # serve docs on :8123
just docs-api         # regenerate API docs

    Add your own recipes in ~/.config/zshand/justfile β€” they're auto-included.

πŸ“Š How ZSHAND ComparesΒΆ

Framework Capabilities Radar Chart
Framework capabilities at a glance β€” ZSHAND covers the full surface area that other frameworks only partially address
Beta (v2.0.0) β€” Active development. Opinionated defaults for dev workstations.
Roadmap β€” Configurable via config.toml. Breaking changes between majors.
156+ auto-generated docs β€” every source file gets a page with Mermaid graphs, like this site.
Zero vendor lock-in β€” pure Zsh + TOML. Import from OMZ, Prezto, or any .zsh file.
<50ms cold start β€” P10k instant prompt + compiled bytecode. 100+ files β†’ one .zwc bundle.
Self-healing shell β€” 3 crashes β†’ Safe Mode. Auto-recovery menu, health checks, PATH auto-repair.

Project Overview

Feature ZSHAND OMZ P10k Prezto Zinit zimfw Antigen zplug sheldon bash-it oh-my-bash
Type Full framework Full framework Prompt theme Full framework Plugin mgr Module mgr Plugin mgr Plugin mgr Plugin mgr Full framework Full framework
Shell Zsh Zsh Zsh Zsh Zsh Zsh Zsh Zsh Zsh+Bash Bash Bash
GitHub stars Private 175k 46k 14k 2.9k 3.8k 7.9k 5.8k 1k 14k 5.9k
Status Active Active Archived Slow Active Active Unmaintained Unmaintained Active Active Active
Written in Zsh Zsh Zsh Zsh Zsh Zsh Zsh Zsh Rust Bash Bash
Config format β†— TOML Shell Shell Shell Shell Shell Shell Shell β†— TOML Shell Shell

Performance & Loading

Feature ZSHAND OMZ P10k Prezto Zinit zimfw Antigen zplug sheldon bash-it oh-my-bash
Cold start <50ms 200-400ms (no compile) N/A (prompt only) 80-150ms 50-100ms (ice tuned) 40-80ms 300-500ms (re-parse) 200-400ms (re-parse) 30-60ms (Rust loader) 200-500ms 150-300ms
Bytecode bundle 100+ files β†’ 1 β†— .zwc No No No No No No No No No No
Auto-compilation Detects stale, β†— recompiles per-dir No No No β†— ice compile β†— compile No No No No No
Lazy loading Each function/widget β†— on first call No N/A β†— Partial β†— Turbo β†— Partial No β†— Deferred β†— Yes No No
Async ops Hooks run β†— after prompt renders No N/A No β†— Turbo No No No No No No
Profiling zprofile β€” ranks β†— slowest files No No No β†— zpmod No No No No No No

Configuration & Extensibility

Feature ZSHAND OMZ P10k Prezto Zinit zimfw Antigen zplug sheldon bash-it oh-my-bash
Override w/o fork Drop file in β†— rc.d/, it wins No No β†— Partial No No No No No β†— Partial No
TOML config Declarative β†— config, no shell code No No No No No No No β†— Yes No No
Load order ctrl 05_foo.zsh β€” number β†— sets priority No No No No No No No No No No
Import frameworks One cmd β†— imports OMZ/Prezto Native No Native β†— Partial β†— Partial β†— OMZ β†— GitHub β†— GitHub No β†— OMZ
3-tier functions Core β†’ plugin β†’ yours (β†— last wins) Plugins N/A β†— Modules No No No No No No No
Custom plugins dir Own dir, β†— profiled + compiled β†— Yes N/A Yes β†— Yes Yes No No No β†— Yes Yes
Themes P10k built in + β†— customizable β†— 150+ Native β†— 30+ No No No No No β†— 60+ β†— 50+

Built-in Features

Feature ZSHAND OMZ P10k Prezto Zinit zimfw Antigen zplug sheldon bash-it oh-my-bash
Functions 31 β†— shell functions β†— ~30 0 β†— ~20 0 ~10 0 0 0 β†— ~20 ~15
Keyboard widgets 20+ β†— bound to keys 0 0 β†— 2 0 0 0 0 0 0 0
Smart hooks 10 β†— hooks, deferred after prompt β†— Plugins N/A β†— 6 β†— Ice No No β†— Tags No No No
PATH healing Detects broken PATH, β†— auto-repairs No No No No No No No No No No
Plugins included 133+ β†— source files, all compiled β†— 300+ N/A β†— 30+ No No No No No β†— 70+ β†— 50+
Completions fzf-powered, β†— compiled in β†— 250+ N/A β†— Yes No No No No No β†— 40+ 30+

Developer Tool Integrations

Feature ZSHAND OMZ P10k Prezto Zinit zimfw Antigen zplug sheldon bash-it oh-my-bash
mise / asdf β†— Deferred load, zero startup cost β†— Plugin N/A No β†— Plugin No No No No No No
Docker Aliases + completions, β†— auto-loaded β†— Plugin N/A β†— Module Plugin No No No No β†— Plugin Plugin
Atuin history Replaces Ctrl-R with β†— fuzzy search Plugin No No Plugin No No No No No No
Git identity Auto-switches name/email β†— per repo No β†— Prompt No No No No No No No No
Per-project env cd into dir β†’ β†— tools activate β†— direnv No No β†— Plugin No No No No No No
nvm / pnpm / bun All managed by β†— mise, one tool β†— Plugin N/A No Plugin No No No No β†— Plugin Plugin
Rust / cargo β†— mise manages toolchain + PATH No N/A No Plugin No No No No No No
Go β†— mise manages version + GOPATH β†— Plugin N/A No Plugin No No No No No No
uv / pip β†— mise manages Python + uv β†— Plugin N/A β†— Module Plugin No No No No No No
Linting / fixing β†— Trunk β€” ShellCheck, shfmt, gitleaks, ruff, prettier + more No No No No No No No No No No

Shell Enhancements

Feature ZSHAND OMZ P10k Prezto Zinit zimfw Antigen zplug sheldon bash-it oh-my-bash
Syntax highlight β†— Pre-compiled into bundle β†— Plugin N/A No β†— Plugin β†— Plugin Plugin Plugin Plugin No No
Auto-suggest β†— Lazy-loaded, no startup cost β†— Plugin N/A No β†— Plugin β†— Plugin Plugin Plugin Plugin No No
FZF integration Ctrl-R, Ctrl-T, Alt-C β†— bound β†— Plugin N/A No Plugin No No No No No No
Clipboard Paste, yank, history β€” 5 β†— widgets No No No No No No No No No No
Dir jumping β†— zoxide frecency, replaces cd β†— Plugin N/A No Plugin No No No No No No
Git aliases 50+ β†— aliases: gaa, gcm, gp, gst… β†— Yes N/A β†— Yes No No No No No β†— Yes Yes
Modern CLI eza, bat, fd, rg β†— wired in No N/A No No No No No No No No

AI & Intelligence

Feature ZSHAND OMZ P10k Prezto Zinit zimfw Antigen zplug sheldon bash-it oh-my-bash
AI commit βŒƒB: stage, diff, message, β†— push No No No No No No No No No No
AI debug βŒƒE: captures stderr + context, β†— suggests fix No No No No No No No No No No
AI context Exports full shell state β†— for LLM No No No No No No No No No No
Doc Assist Queue β†— docgen parses headers β†’ queues missing docs for AI fill No No No No No No No No No No
Auto Doc Website β†— MkDocs site from your code + framework β€” Mermaid graphs, search No No No No No No No No No No
Debug Assist Queue Coming soon β€” AI-triaged error queue from session logs No No No No No No No No No No
Test Fail Queue Coming soon β€” failing tests auto-queued for AI diagnosis No No No No No No No No No No

Safety, Observability & Documentation

Feature ZSHAND OMZ P10k Prezto Zinit zimfw Antigen zplug sheldon bash-it oh-my-bash
Safe mode Broken config? Boots clean, β†— tells why No No No No No No No No No No
Health check health β€” one word, β†— full diagnostic No No No No No No No No No No
Telemetry Per-command timing + β†— resource tracking No No No No No No No No No No
Secrets Auto β†— chmod 600 on keys, tokens, env No No No No No No No No No No
Doc Frontend MkDocs site with β†— 134 pages, search, Mermaid graphs β€” your code gets pages too β†— README β†— README β†— README β†— README β†— README README README β†— Docs β†— README README
Dependency graphs Auto-generated β†— Mermaid graphs per file β€” who calls what No No No No No No No No No No
Update command zupdate β€” pull, β†— recompile, verify β†— Yes N/A Yes β†— Yes β†— Yes No No No β†— Yes Yes

πŸ”„ Startup PipelineΒΆ

Startup Timeline
Every millisecond accounted for β€” P10k instant prompt to background recompile in ~47ms (Oh My Zsh: 200-400ms)
Precision-engineered pipeline β€” every stage numbered, timed, and recoverable. Hook into any point from ~/.config/zshand/.

  • Hook Into Any Stage

    Your config directory When it runs Use case
    init.d/ Before core modules Early env setup, PATH fixes, feature flags
    rc.d/ Replaces or inserts into core Override 06_engine, add 05_my_module between steps
    post.d/ After everything Final tweaks, notifications, background tasks
    hooks/ Inside 18_hooks Add 05_myapp.zsh between 02_atuin and 20_docker
    widgets/ Inside 16_widgets Override or add new keyboard widgets
    functions/ Inside 90_functions Override any framework function (highest priority)

    All directories live under ~/.config/zshand/.

    Configure Architecture

  • Key Startup Features

    Feature What it does
    Perf budget Set ZSHAND_PERF_BUDGET=5 β€” warns if any file takes > 5ms
    Stale .zwc check Detects when sources are newer than compiled bundles
    Background recompile auto_full = true recompiles after first prompt, zero cost
    Dev mode dev_mode = true skips bundles, loads raw source for hacking
    TOML config Parses config.toml β†’ ZSHAND_* env vars, no shell syntax
    TOML keybindings Remap any widget from keybindings.toml
    Health check Validates required tools are installed at startup
    Startup sentinel Logs completion, tracks failures, feeds Safe Mode

    Startup Pipeline Performance

⌨️ Keyboard Widgets¢

20+ ZLE Widgets β€” every widget is lazy-loaded: 1ms stub at startup, 10-20ms on first keypress. After that, instant. Your shell starts fast and stays fast even with 20+ keybindings registered.
Fully Customizable β€” override any binding in keybindings.toml (TOML, not shell). Add your own widgets in ~/.config/zshand/widgets/ β€” they get lazy-loaded automatically, no config needed.
Coming Soon Collision detection for widget keybindings vs OS hotkeys and VS Code shortcuts. Auto-warns on conflicts, suggests alternatives, and lets you remap in keybindings.toml.

  • Inbound (Clipboard/Buffer)

    Key Widget Action
    βŒƒ P pastem Smart paste, strip fences
    βŒ₯ P pasteraw Raw paste, exact format
    βŒ₯ H cliph Clipboard history picker
    βŒ₯ D pjump Project jump via zoxide

  • AI & Outbound

    Key Widget Action
    βŒƒ O bufcopy Buffer β†’ clipboard
    βŒƒ G cplast Last output β†’ clipboard
    βŒƒ E aidebug AI diagnose last error
    βŒƒ B aicmit AI commit + push
    βŒƒ K qlog Timestamped note

  • Edit & Transform

    Key Widget Action
    βŒƒ J jtog JSON pretty ↔ mini
    βŒƒ X bufedit Edit buffer in $EDITOR
    βŒƒ A aliexp Expand alias at cursor
    βŒ₯ A aliasf Fuzzy alias search
    βŽ‹ βŽ‹ sudot Toggle sudo prefix

  • Pickers & Search

    Key Widget Action
    βŒ₯ B bpick Binary picker via fzf
    βŒ₯ F fpick Function picker
    βŒ₯ ↡ ctxpick Context: branch, file
    βŒ₯ M manf Man page finder
    βŒ₯ ? whelp Keybinding reference

Widgets Guide Source Reference

🧠 Core Modules¢

11 numbered modules loaded in strict order. Every module is overridable β€” drop NN_name.zsh in rc.d/ to replace or insert between any step. Each has a structured header and auto-generated docs.
Module🎯 Whyβš™οΈ WhatπŸ”§ How
02 VariablesEvery module needs a shared baseSets XDG base dirs, log paths, cache root, and a machine-unique ID β€” all modules read from theseAuto β€” just works
04 PATHStop $PATH growing into a messBuilds a deduped, priority-ordered $PATH β€” Homebrew, cargo, go, pip, local bin, your path.txtEdit path.txt
06 EngineSpeed + full observabilityCompiles .zsh β†’ .zwc bytecode, records per-command timing telemetry, enforces file permissionszr to recompile
08 AuditKnow exactly when things breakTracks load failures, logs health events, counts consecutive crashes β†’ triggers Safe Mode automaticallyhealth / zcheck
10 OptionsSane defaults out of the boxGlobbing, 50k history with dedup, fuzzy/partial/case-insensitive completion matching, safety optionsOverride in rc.d/
12 CompletionsTab should just work everywhereRuns compinit, extends $fpath with your dirs, enables fuzzy matching and partial-word completionAuto β€” add to fpath
14 AliasesModern CLI tools everywhereMaps ls→eza, cat→bat, rm→trash, git shortcuts, Docker aliases, pipe aliases — 50+ totalYours always win
16 WidgetsKeyboard-driven workflowRegisters 20+ ZLE widgets as lazy stubs β€” binds keys but defers loading until first keypresskeybindings.toml
18 HooksIntegrations without startup costDiscovers and sources 10 numbered hooks β€” mise, Atuin, Docker, zoxide, git β€” all deferred by defaultDrop .zsh in hooks/
20 PluginsUse exactly what you wantLoads from plugins.txt whitelist β€” each plugin gets its own strategy (immediate/lazy/defer/disabled)Edit plugins.txt
90 FunctionsYour code always wins3-tier autoload: user functions/ > private_functions/ > framework β€” drop a same-named file to overrideDrop file in functions/

⏱️ Configurable Loading Strategy¢

Fine-grained control over how and when every component loads. Applies to hooks, plugins, and widgets. Each item gets its own strategy β€” change one line in plugins.txt to switch.
StrategyWhen it loadsCostBest for
⚑ ImmediateShell init, in numbered orderFull load timeSyntax highlighting, completions, prompt
😴 Lazy1ms stub β†’ compiles on first use10-20ms on first callCommands you don't use every session
⏳ DeferredAfter first prompt rendersZero perceivedHeavy integrations, hooks (default)
β›” DisabledNever (commented out)NoneTemporarily disable without deleting
plugins.txt lineWhyExample
⚑zsh-syntax-highlighting immediateMust be ready for first keystrokezsh-completions immediate
😴zsh-autosuggestions lazyCompiles on first usemy-custom-plugin lazy
⏳heavy-integration deferLoads after prompt rendersmy-omz-plugin defer
β›”# disabled-pluginCommented = off, no deletion needed# slow-plugin defer
Debug tip β€” ZSHAND_NO_LAZY=1 forces everything immediate. Useful when a lazy or deferred plugin misbehaves β€” load it synchronously to see the real error.
Want full operability instantly? β€” Set all plugins to immediate in plugins.txt. Adds ~20-40ms to startup but everything is ready on the first keystroke.

Architecture Hooks Widgets

πŸ“ Your ~/.config/zshandΒΆ

Everything lives in ~/.config/zshand/. The framework never needs editing β€” updates pull cleanly because your config is separate.
Override Without Forking
Drop a file to override anything β€” framework updates never touch your config

Configuration Guide

File / DirectoryWhenWhat it does for you
βš™οΈconfig.toml1. Early initControls the entire framework without shell syntax β€” dev mode, perf budgets, quiet mode, auto-compile. Parsed into ZSHAND_* env vars before anything else loads.
🌐env.zsh1. Early initYour machine-specific environment β€” EDITOR, BROWSER, proxy settings, FZF_DEFAULT_OPTS. Auto-exported so child processes inherit everything.
πŸ”secrets.zsh1. Early initAPI keys & tokens loaded before any network-touching code. chmod 600 auto-enforced every startup β€” even if you accidentally loosen permissions.
οΏ½init.d/2. Before coreRuns before any core module β€” use for early PATH fixes, feature flags, or env overrides that core modules depend on.
πŸ›€οΈpath.txt3. PATH buildOne path per line, no shell syntax. Deduped and priority-ordered β€” stops $PATH from growing into a mess across shell restarts.
πŸ“‚bin/3. PATH buildYour own CLI tools β€” automatically added to $PATH. Drop a script here and it's available everywhere.
πŸ“‚rc.d/4. Core loadOverride or insert into the core pipeline β€” 05_foo.zsh loads between 04_path and 06_engine. Full control of ordering.
οΏ½aliases.zsh5. After coreYour aliases, loaded after framework aliases β€” yours always win. Override ll, gp, or any built-in alias.
πŸ“‚hooks/6. Hook loadYour tool integrations β€” numbered alongside framework hooks. Add 05_myapp.zsh to run between mise and Atuin.
οΏ½git-identity.conf6. Hook loadPersisted git name, email, signing key β€” survives reinstalls. The gitid hook reads this for multi-identity switching.
πŸ“‚widgets/7. Widget loadYour keyboard widgets β€” override built-ins or add new ones. Lazy-loaded automatically so they don't cost startup time.
⌨️keybindings.toml7. Widget loadRemap any widget keybinding in TOML β€” aicmit = "^G". No need to remember bindkey syntax or edit source.
🧩plugins.txt8. Plugin loadWhitelist controls which plugins load and how β€” name strategy per line. Comment a line to disable without deleting.
πŸ“‚plugins/8. Plugin loadYour plugins β€” drop any .zsh file here and add to plugins.txt. Works with OMZ imports and native sources.
πŸ“‚functions/9. Func loadHighest priority autoload β€” drop a same-named file to override any framework function. No fork needed.
πŸ“‚post.d/10. After allRuns after everything is loaded β€” final tweaks, notifications, background tasks, startup messages.

  • config.toml

    Controls quiet modes, debug flags, performance budgets, dev mode, and plugin strategies. All settings map to ZSHAND_* environment variables β€” parsed by 16_az_load_toml_config. No shell syntax needed.

  • keybindings.toml

    Remap any widget keybinding without touching framework code. Parsed by 17_az_bindkey_from_toml. Example: aicmit = "^B" to "^G".

  • secrets.zsh

    API keys, tokens, credentials. The engine enforces chmod 600 on every startup. Never committed. Coming soon: Doppler and Cloudflare Secrets integration for team/edge secret syncing.

  • Config Templates

    samples/user-config/ ships ready-to-use templates. setup.zsh copies them on first install. Every directory has a README explaining the override pattern.

πŸ”§ Shell FunctionsΒΆ

31 functions with 3-tier priority: ~/.config/zshand/functions/ (yours) > private_functions/ > functions/ (framework). Override any function by dropping a same-named file.

  • Health & Diagnostics

    Function What it does
    health Full system check: engine, tools, SSH, git, clipboard, disk
    ztop Live framework status dashboard
    zpath PATH audit: duplicates, broken, missing entries
    pathfix Auto-heal PATH: dedup + remove dead entries
    zports List processes using network ports
    Quick health check
    health          # full system diagnostic
ztop            # live dashboard (refreshes)
pathfix --dry   # preview PATH fixes

  • Productivity & Git

    Function What it does
    extract Universal archive extractor (tar, zip, 7z, rar, etc.)
    seek Recursive content search with ripgrep
    gitprune Clean up merged/stale remote branches
    gundo Undo last git commit safely
    tossh Convert HTTPS remotes to SSH
    Everyday shortcuts
    extract archive.tar.gz  # any format
seek "TODO" --type zsh  # ripgrep wrapper
gitprune                # clean stale branches

  • Logging & Analytics

    Function What it does
    logstat 30-day command analytics: success rate, top commands
    bootlog View/tail shell init logs
    zlog Session log viewer: summary, tail, search
    zwidgets List all loaded widgets with bindings
    zhelp Searchable help for all framework commands
    What happened?
    logstat         # 30-day command analytics
zlog tail 20    # last 20 session events
bootlog         # startup init log

  • Framework Internals (also available to your scripts)

    Function What it does
    gum_io Beautiful gum TUI helpers
    clipboard_copy Cross-platform clipboard write
    clipboard_paste Cross-platform clipboard read
    time_millis Precision timing (auto-detects fastest timer)
    zrun Telemetry-wrapped command execution

    All 18 shared functions

πŸ”Œ Hooks & PluginsΒΆ

  • Hooks: Numbered, Deferred, Configurable

    10 framework hooks loaded by 18_hooks in numeric order. Each runs deferred after first prompt by default β€” configurable to immediate, lazy, or disabled. Add yours in ~/.config/zshand/hooks/ with any number for ordering.

    Hook Integration What it does
    01_mise mise Polyglot runtimes: Node, Python, Go, Rust, Bun, pnpm
    02_atuin Atuin Encrypted cross-machine shell history sync
    05_ssh-agent ssh-agent Auto-start agent, add keys, forwarding
    20_docker Docker Completions, aliases (dps, dclean), context switching
    30_zoxide zoxide Smart cd with frecency-based directory jumping
    40_wrangler Wrangler Cloudflare Workers/Pages CLI completions
    50_gitid Git Multi-identity SSH/GPG switching per repo
    80_archclean Filesystem Auto-cleanup old archives and temp files
    81_wlclean Wayland Clipboard sanitization and leak prevention

  • Plugins: Whitelist + OMZ Compatible

    Controlled via ~/.config/zshand/plugins.txt β€” whitelist mode, not load-everything. Each plugin gets its own load strategy (immediate / lazy / defer).

    Plugin Strategy What it does
    zsh-syntax-highlighting immediate Real-time command coloring
    zsh-autosuggestions lazy Ghost-text suggestions from history
    zsh-completions immediate 1000+ extra completions
    Your OMZ plugins any Import with import-ohmyzsh-plugins
    Any .zsh source any Drop in plugins/ and add to plugins.txt β€” no wrapper needed
    ~/.config/zshand/plugins.txt
    zsh-syntax-highlighting immediate
zsh-autosuggestions lazy
zsh-completions immediate
my-custom-plugin defer        # your own .zsh file
# my-omz-plugin defer

    Plugin System

βš–οΈ Hooks vs PluginsΒΆ

πŸͺ Hooks🧩 Plugins
πŸ“ WhenShell init, numbered order β€” deferred after first prompt by defaultOn demand β€” each plugin chooses: immediate, lazy, or defer
🎯 PurposeTool integrations that configure environment: PATH entries, env vars, completions, daemon startupStandalone feature bundles: syntax highlighting, autosuggestions, OMZ compatibility, custom functionality
πŸ“‚ Location~/.config/zshand/hooks/~/.config/zshand/plugins/ + plugins.txt
βš™οΈ ControlNumbered filenames (05_myapp.zsh) β€” ordering by prefix, runs between framework hooksWhitelist in plugins.txt β€” each line: name strategy. Comment to disable, no deletion needed
πŸ”Œ Examplesmise (runtimes), Atuin (history), Docker (completions), zoxide (cd), git identity (SSH/GPG)zsh-syntax-highlighting, zsh-autosuggestions, zsh-completions, imported OMZ plugins, any .zsh file
βž• Add newDrop numbered .zsh file in hooks dir β€” immediately part of the pipelineDrop .zsh in plugins dir, add name strategy to plugins.txt β€” or import from OMZ

πŸ› οΈ CLI Tools (bin/)ΒΆ

45 CLI tools in bin/, all added to PATH. Add your own in ~/.config/zshand/bin/.
CategoryToolWhat it does
πŸ”§ BuildzrRecompile everything in ~1s β€” run after any edit to framework or config files
πŸ”§ BuildzfullCompile framework + your hooks, widgets, functions, env, secrets into one .zwc bundle (~3s)
πŸ”§ BuildzupdateFull maintenance: git pull β†’ recompile β†’ update plugins β†’ verify health β†’ restart β€” one command
πŸ€– AIaicontextExport your entire project context (tree, git state, deps, env) as a structured manifest for Cursor, Windsurf, or Claude
πŸ€– DevscaffoldGenerate new widgets, functions, hooks, or bin tools from templates β€” with headers, tests, and docs pre-filled
οΏ½ ProfilezprofileBuild an instrumented bundle, launch a profiled shell, and get a ranked report of your slowest files
🧭 NavzdJump to any directory by partial name β€” 2-char shortcut powered by zoxide frecency
🧭 NavzeOpen any file in $EDITOR with fuzzy path completion β€” 2-char shortcut, no full paths needed
οΏ½ Importimport-ohmyzsh-pluginsClone OMZ, pick the plugins you want, copy them to your config β€” they work with ZSHAND's loader immediately
οΏ½ Importimport-p10k-themeBring your existing P10k config β€” it gets compiled into the bytecode bundle for zero-cost loading
οΏ½ DocsdocgenParse HEADER_STANDARD from every source file and generate full Markdown doc pages with Mermaid graphs
πŸ–₯️ SystempcopyCopy files with a live progress bar, ETA, and transfer speed β€” replaces bare cp for large files
πŸ–₯️ SystempersyncPersistent rsync that auto-retries on failure, resumes where it left off, and respects bandwidth limits

CLI Reference Source Reference

πŸ“‘ Telemetry & ObservabilityΒΆ

No other shell framework offers this level of visibility into what your shell is doing.
zprofile β€” Startup Profiler
# Builds an instrumented .zwc bundle that wraps every file and directory
# load with precision timing. Launches a profiled shell, captures data,
# and generates a ranked performance report.
zprofile              # build instrumented bundle + run profiled shell
zprofile --report     # show last report (no restart)
zprofile --full       # include widgets + hooks profiling
zprofile --rebuild    # force rebuild of profile bundle
zprofile --all        # show all items, not just top 5
**⚑ Features** | Feature | Detail | |:--------|:-------| | **Per-file timing** | Every `.zsh` file measured individually | | **Per-directory timing** | Aggregate timing for core, hooks, widgets, plugins | | **Perf budget** | `ZSHAND_PERF_BUDGET=5` in [`config.toml`](USER_CONFIG.md) warns if any file > 5ms | | **Top-N report** | Shows slowest 5 files by default, `--all` for everything | | **Debug mode** | `ZSHAND_DEBUG=1` shows inline timing during startup |
**πŸ“Š Components** | Component | What it does | |:----------|:-------------| | [`zrun`](source/core/06_engine.md) | Wraps execution with automatic logging + timing | | [`init_log_append`](source/shared_functions/03_init_log_append.md) | Records every startup event β†’ feeds [Safe Mode](SAFE_MODE.md) | | [`time_millis`](source/shared_functions/06_time_millis.md) | Auto-detects fastest timer: `EPOCHREALTIME` > `date +%N` > `date +%s` | | [`logstat`](source/functions/logstat.md) | 30-day command analytics: success rate, top commands | | [`zlog`](source/functions/zlog.md) | Session log viewer: summary, tail, pattern search |
Audit your shell
zcheck              # last command: exit code, duration, stderr
logstat             # 30-day analytics: top commands, fail rate, patterns
logstat --top 20    # show top 20 most-used commands
zlog summary        # session overview: events, errors, timing
zlog tail 20        # last 20 session events with timestamps
zlog search "fail"  # grep session logs for patterns
bootlog             # per-module startup timing breakdown

Performance Guide zprofile Reference Engine Reference

πŸ’» Aliases & Modern CLIΒΆ

Modern ReplacementsΒΆ

Every classic Unix tool gets a faster, prettier drop-in replacement β€” auto-aliased by 14_aliases.
ClassicModernWhat you getAliases
lsezaSee git status, file icons, and tree view in every listing β€” know what changed at a glancell, lt, la
catbatSyntax-highlighted output with line numbers and git diff markers β€” reading code in terminal finally workscat β†’ bat
findfd10Γ— faster, auto-ignores .gitignore and hidden files β€” no more find . -name '*.js' -not -path './node_modules/*'find β†’ fd
greprgSmart-case search that skips binaries and respects .gitignore β€” instant results in huge reposG pipe alias
topbtopBeautiful TUI with CPU, RAM, disk, network graphs β€” see exactly what's eating resourcestop β†’ btop
mantldrPractical examples instead of walls of text β€” learn a command in 10 seconds, not 10 minuteshelp
diffdeltaSide-by-side diffs with syntax highlighting and line numbers β€” Git uses it automaticallyGit auto-uses
cdzoxideType z proj to jump to ~/code/my-project β€” learns from your habits, gets smarter over timez, zi
dudustVisual disk usage tree sorted by size β€” instantly find what's filling your drivedu β†’ dust
psprocsColorized, searchable process list with tree view β€” find and kill processes without ps aux | grepps β†’ procs
curlcurlieCurl with httpie-style colored, formatted output β€” see headers and JSON beautifullycurl β†’ curlie

Alias LayersΒΆ

Two layers β€” yours always win. User aliases load after framework aliases so your overrides take priority.
CategoryLayer 1 β€” FrameworkLayer 2 β€” User
πŸ“‚ Source14_aliases.zsh β€” loaded as core module #14, defines 50+ aliases across all categories~/.config/zshand/aliases.zsh β€” your personal overrides, loaded after all core modules
πŸ“ WhenCore module load (step 14 of 16) β€” after PATH, engine, pluginsAfter all core modules β€” guaranteed to override anything in Layer 1
🧭 Navigation.., ..., ...., ~, - (previous dir)Your shortcuts, e.g. alias proj='cd ~/projects'
πŸ”€ Gitgaa, gcm, gp, gco, gst, gl, gd, gbe.g. alias gp='git push --force-with-lease'
🐳 Dockerdps, dclean, dlog, dexec, dstope.g. alias dps='docker ps --format table'
πŸ”— PipelinesL (less), G (grep), JQ (jq), H (head)e.g. alias Y='| yq', alias C='| wc -l'
πŸ›‘οΈ Safetycp -i, mv -i, rm -i β€” interactive prompts prevent accidentse.g. alias rm='rm -rf' (brave mode)
⚑ PriorityBase β€” always present, never changesWins β€” overrides any framework alias

πŸ“¦ Compile & Build SystemΒΆ

Zsh can execute pre-compiled .zwc bytecode ~5Γ— faster than raw source. Most shell frameworks load raw .zsh files on every startup. ZSHAND compiles everything into bytecode β€” your shell loads one pre-compiled bundle instead of parsing 100+ files.
Build System β€” 7 compile tools from zr (1s quick recompile) to zfull (framework + your config in one bundle). Run zr after any edit, zfresh for a clean slate, zprofile to find what's slow.
Auto-Full Mode β€” Set auto_full = true in config.toml and forget manual compiles. Detects stale bundles, recompiles after first prompt β€” zero perceived cost. All your files merged into one .zwc.
Performance Guide β€” Set ZSHAND_PERF_BUDGET=5 to warn if any file takes >5ms. zprofile builds an instrumented bundle and ranks your slowest files. ZSHAND_DEBUG=1 for inline timing.

Bytecode CompilationΒΆ

ToolWhat it compilesSpeedResultWhen to use
zrFramework sources~1sPer-dir .zwcAfter editing any file
zmonoAll β†’ single .zwc~2sOne portable bundleDeployment
zfullFramework + your config~3sComplete bundleInclude user config
zprimePer-directory bundlesAutoPer-dir .zwcRuns automatically
zfreshClean rebuild + restart~4sFresh shellSomething broken
zrebuildSyntax-validated rebuild~5sValidated bundleCI / deploy
zprofileInstrumented profiling~3sTiming reportFind slow files

πŸ” Secrets & SecurityΒΆ

secrets.zsh β€” auto-secured with chmod 600 by the engine on every startup. Never committed to git. Coming soon: Doppler + Cloudflare Secrets integration.
Trunk auto-lint β€” ShellCheck, shfmt, gitleaks, trufflehog, cspell, markdownlint, ruff, prettier, yamllint β€” all pre-configured. Secret scanning on every commit.

πŸ“– Documentation & GuidesΒΆ

πŸ“ Architecture & InternalsπŸ‘€ User GuideπŸ› οΈ Developer
Architecture β€” 5-layer design, overrides
Core Modules β€” 11 numbered modules
Startup Pipeline β€” P10k to sentinel
Auto-Full Mode β€” auto user-config compile
Performance β€” profiling, perf budgets
Build System β€” .zwc compilation, just 		Configuration β€” config.toml, keybindings
Functions β€” 3-tier priority, autoloading
Widgets β€” 20+ keyboard shortcuts
Hooks β€” tool integrations, ordering
CLI Tools β€” 45 commands
Safe Mode β€” auto-recovery
Troubleshooting β€” common fixes 		Contributing β€” PR workflow, standards
Style Guide β€” naming, headers
Testing β€” ShellSpec, CI
Security β€” secrets, Trunk, scanning
Shared Functions β€” 18 internals
Private Functions β€” framework helpers
156 auto-generated source pages with Mermaid dependency graphs Β· Changelog Β· Project Summary

πŸ—οΈ Installer & SetupΒΆ

cloner.sh β€” One-Line Install

bash <(curl -fsSL https://raw.githubusercontent.com/presempathy/zshand/main/cloner.sh)
StepWhat happens
1. OS detectionDebian, Manjaro, macOS, WSL auto-detected
2. PrerequisitesInstalls gum for beautiful TUI
3. SSH keysGenerates ED25519 keys + GPG signing
4. Git identityName, email, signing key β€” persisted across reinstalls
5. CloneSSH preferred, HTTPS fallback
6. Shell profilesWrites .zshrc, .zshenv, .zprofile
7. PackagesInstalls 70+ modern CLI tools
8. CompileBuilds .zwc bytecode bundle
Flags: --dry-run, --non-interactive, --update, --uninstall. Compiled single-file via just cloner.

Installers

OS Packages (70+)

A modern dev workstation needs modern tools. The installer replaces slow, limited Unix defaults with fast, Rust/Go alternatives β€” then ZSHAND wires each one into aliases, completions, and integrations so they just work.
CategoryWhyTools
File mgmtSee files with color, git status, icons β€” instantlyeza, bat, fd, ripgrep, trash-cli
NavigationJump anywhere by frecency, fuzzy-find everythingfzf, zoxide, tree
GitTUI git, beautiful diffs, PR management from terminallazygit, delta, gh
SystemMonitor CPU/RAM/disk with beautiful TUIsbtop, dust, duf, procs
DevPolyglot runtimes, fast Python, task runner, JSONmise, uv, just, jq
NetworkPretty curl, DNS lookup, visual pingcurlie, dog, gping
SecurityCatch leaked secrets and bad shell code before commitgitleaks, shellcheck, shfmt
Re-run cloner.sh --update anytime to pick up new packages. pkgsync verifies everything is installed β€” pkgsync --fix installs anything missing.

🐳 DevContainer & CI¢

Ready-to-use development environment + fully automated CI/CD pipeline. Open a DevContainer for instant shell dev, or push to main and let GitHub Actions handle testing, linting, and deployment.
AreaDevContainerCI / CD PipelineConfig
πŸ—οΈ PlatformVS Code, Codespaces, devcontainer CLIGitHub Actions on push to main.devcontainer/
🐚 ShellZsh + full framework pre-compiledShellSpec tests (Ubuntu + macOS)spec/ test suite
πŸ” LintingShellCheck, shfmt, Trunk, ShellSpecTrunk: ShellCheck, shfmt, gitleaks.trunk/
πŸ“– DocsMkDocs preview on port 8000MkDocs build + Mike versioningjust docs-*
πŸš€ Deployzfresh rebuilds in containerCloudflare Pages deploy.github/workflows/
πŸ’° CostFree (local or Codespaces)Free (GitHub Actions)Timeout guards built in

Build System Testing