Skip to content

ZSHAND

A high-performance, opinionated Zsh framework for developers who don't wait. Compiled bytecode, modular architecture, 20+ keyboard widgets, and a self-documenting codebase — all under 50ms cold start.

v2.0.0 46.9ms startup Beta
Quick Start GitHub
133
<div class="stat-label">Source Files


20+
Widgets

46.9ms
Cold Start
31
CLI Tools

Features

  • Blazing Fast

    46.9ms cold start with compiled .zwc bundles. Auto-Full mode gives you zero-config production performance — just set one flag.

    Performance Guide

  • Modular Architecture

    Every component lives in its own directory with numeric load ordering. Override any file from your config dir — no framework edits needed.

    Architecture

  • 20+ Keyboard Widgets

    AI commit messages, smart paste, clipboard history, JSON toggle, project jump, sudo toggle — all bound to keyboard shortcuts.

    Widgets Guide

  • Smart Hooks

    Critical tools load instantly. Everything else defers to keep your first prompt fast. Lazy loading saves 20–80ms at startup.

    Hooks Guide

  • Fully Tested

    Per-directory test suites, ShellSpec BDD specs, and CI integration. Every function has a spec. Every edge case has a test.

    Testing Guide

  • Self-Documenting

    Every file has a structured header with usage, dependencies, examples, and exit codes. Headers auto-generate API docs, tests, and AI context.

    Header Standard

Why ZSHAND?

If you love Oh My Zsh's rich ecosystem but hate the 300ms startup tax — or you love Powerlevel10k's speed but want a full framework, not just a prompt theme — ZSHAND gives you both.

  • Best of Both Worlds

    P10k's instant prompt + compiled .zwc bytecode bundles give you 46.9ms cold starts. But unlike P10k, you get a complete framework: 133 source files, 20+ widgets, 31 CLI tools, and smart hooks — all lazy-loaded.

  • Override Without Forking

    Drop any file into ~/.config/zshand/rc.d/ with the same numeric prefix to override a core module. Add widgets to ~/.config/zshand/widgets/. Edit keybindings.toml to remap any key. Zero framework edits — ever.

  • AI-Native Workflow

    Ctrl+B → aicmit builds a commit prompt from your staged diff, project context, and PROFILE.md, copies it to clipboard, opens your editor — then commits and pushes. Ctrl+E → aidebug diagnoses errors. No API keys in your shell.

  • Self-Healing Shell

    3 init failures in 5 minutes? ZSHAND enters Safe Mode automatically: minimal PATH, emergency prompt, and a recovery menu with one-command fixes. Your shell never stays broken.

  • Smart Paste & Clipboard History

    Ctrl+P → pastem strips markdown fences, prompt characters, and joins multi-line snippets with &&. Alt+H → cliph fuzzy-searches your full clipboard history with live preview. Paste from AI docs without cleanup.

  • Project Navigator

    Alt+D → pjump opens a zoxide-powered fuzzy finder showing git branch, status, and recent files for every project under ~/code. Pick a project, instantly cd there.

How ZSHAND Compares

Feature ZSHAND Oh My Zsh Powerlevel10k Prezto Zinit
Cold start time 46.9ms 200-400ms N/A (prompt only) 80-150ms 50-100ms
Compiled bytecode (.zwc) Auto No No No Optional
Modular architecture Per-directory Plugin-based N/A Module-based Plugin-based
Numeric load ordering Yes No No No No
Config override (no fork) Yes No Yes Partial No
Built-in ZLE widgets 20+ 0 0 2 0
AI-assisted commit aicmit No No No No
Per-file test suites Yes Partial No No No
ShellSpec BDD specs Yes No No No No
Header-driven auto-docs Yes No No No No
Dependency call-tree graph Graphviz No No No No
Smart hooks (lazy load) Yes No N/A Partial Yes
Safe mode Yes No No No No
Self-healing .zshrc guard Yes No No No No
Versioned docs (Mike) Yes Wiki No No No
Type Full framework Full framework Prompt theme Full framework Plugin manager

Beta (v2.0.0) — ZSHAND is in active development. It is opinionated by design: sensible defaults that work out of the box for developer workstations. We're progressively making opinions configurable via config.toml overrides. Expect breaking changes between major versions. Not yet recommended for production servers.

Quick Start

# Clone
git clone https://github.com/presempathy/zshand.git ~/code/zshand

# Run interactive setup (installs deps, creates config dir)
zsh ~/code/zshand/setup.zsh

# Enable fast mode (compiled bundles)
echo 'export ZSHAND_AUTO_FULL=1' >> ~/.zshenv

# Start your new shell
exec zsh

# Clone
git clone https://github.com/presempathy/zshand.git ~/code/zshand

# Setup
zsh ~/code/zshand/setup.zsh

# Dev mode: skips bundles, loads source directly, enables debug
echo 'export ZSHAND_DEV_MODE=1' >> ~/.zshenv
exec zsh

Architecture at a Glance

Call Tree

Internal dependency graph — auto-generated from source headers via Graphviz

Documentation

Section Guides
Architecture Architecture · Core Modules · Startup · Auto-Full Mode
User Guide Configuration · Functions · Widgets · Hooks · CLI Tools
Developer Contributing · Style Guide · Testing · Performance
Reference Header Standard · Shared Functions · Private Functions
Project Changelog · Summary · Security