🏗️ ZSHAND Architecture¶

🎯 Read this first if you're new to the codebase. This document explains how the framework is structured, how it boots, how bundles and overrides work, and where your config plugs in.

Entry: zshrc.zsh → shared_functions + startup → core (02→90) → hooks → user post.d.
Speed: Use a full bundle (ZSHAND_AUTO_FULL=1 or zfull) for <50 ms cold start.
Override: Same basename in ~/.config/zshand/rc.d/ (or hooks/functions/widgets) replaces the framework file.

• ⚡ Performance first — target <50 ms cold start, <10 ms warm
• 🧩 Modular — every directory is independently compilable
• 🔄 Override-friendly — users replace any framework file by dropping a file in config
• 🛡️ Fail-safe — safe mode and graceful degradation at every layer
• 📐 Convention-driven — numbered prefixes enforce load order; no magic, no plugins

🔗 Related documents¶

In this doc: How it's structured → Directory structure → Boot sequence → zshrc entry point → Bundles → Overrides → Key subsystems → Hooks → Env vars.

How it's structured and works together¶

The diagram above shows the five layers: User space (your config dir), Startup pipeline (shared_functions + startup scripts), Core modules (variables → path → engine → … → functions), Extensions (hooks, then functions and widgets), and Post-init (your post.d scripts). One entry point — zshrc.zsh — runs them in a fixed order so behavior is predictable and overridable.

Why it’s built this way:

• Single entry point — Everything goes through zshrc.zsh. No plugin manager, no magic; you can trace exactly what runs and when.
• Layers — Primitives (shared_functions) load first; then startup (TOML, safe mode, health); then core (config and engine); then extensions (hooks, functions, widgets). Your config is merged in at defined points (rc.d with core, separate dirs for hooks/functions/widgets), so framework updates never overwrite you.
• Bundles — Instead of sourcing dozens of files every time, the build system compiles directories (or the whole stack) into bytecode. One read, one parse: cold start drops from hundreds of ms to tens. The “how” (which strategy: full bundle, per-dir, or individual files) is chosen at boot.
• Overrides — Same basename in your config replaces the framework file; different name adds. You get full control without forking.

The image summarizes this: your config and the framework meet at clear boundaries (init.d, rc.d, post.d, and the parallel dirs for functions/widgets/hooks). The sections below fill in directory layout, boot sequence, bundle types, and override rules so you can find things and change behavior.

📁 Directory structure¶

The repo is a flat set of directories under one root. Each directory has a single responsibility and is compiled to its own bundle (or included in the full bundle). Entry point: zshrc.zsh (sourced by ~/.zshrc). Bootstrap only: setup.zsh (first-time install and OS setup).

At a glance¶

Where to find or change what¶

Full config layout: Config.

Tree by role¶

Entry and bootstrap

zshand/
├── zshrc.zsh          Entry point (sourced by ~/.zshrc)
└── setup.zsh          First-time bootstrap & OS setup (installers use this)

Primitives and startup (load before core)

shared_functions/     Low-level utilities — stderr, timing, bytecode load, clipboard
│   ├── 01_stderr_error.zsh
│   ├── 06_time_millis.zsh
│   ├── 11_source_with_zwc.zsh
│   ├── 15_load_file_timed.zsh
│   └── ...
startup/               Early pipeline — dev check, TOML, safe mode, health
│   ├── 05_az_dev_mode_check.zsh
│   ├── 21_az_health_validate_tools.zsh
│   ├── 24_az_safe_mode.zsh
│   └── ...

Core pipeline (02→90; user rc.d/ merged by basename)

core/                  Framework core — one module per concern
│   ├── 02_vars.zsh        Variables & identity (first in core)
│   ├── 04_path.zsh       PATH construction
│   ├── 06_engine.zsh     Build engine (zprime, zr, zfull), zrun, completion
│   ├── 08_audit.zsh      Integrity & telemetry
│   ├── 10_options.zsh    Zsh options (setopt)
│   ├── 12_completions.zsh Completion system
│   ├── 14_aliases.zsh    Shell aliases
│   ├── 16_widgets.zsh    ZLE widget registration
│   ├── 18_hooks.zsh      Hook classification & loader
│   ├── 20_plugins.zsh    Plugin management
│   └── 90_functions.zsh  Function autoloading

Extensions (user-facing; merged with config dirs)

functions/             Shell utilities (add_path, health, ztop, …)
widgets/               ZLE widgets (paste, AI commit, git branch, …)
hooks/                 Tool hooks (mise, atuin, docker, zoxide, …)
bin/                   CLI tools on PATH (zr, zfull, aicontext, …)

Build and internal

build/                 Compilation, profiling, load strategy
│   ├── compile_full_bundle.zsh
│   ├── compile_profile_bundle.zsh
│   ├── profile_bundle_report.zsh
│   └── ...
private_functions/     Internal helpers (not for user config)
lib/                    Support (e.g. lib/rebuild/ for incremental compile)
config/                 Framework config (e.g. profile-exceptions.conf)

Project and docs

installers/            OS-specific system installers
tests/                 ShellSpec test suites
docs/                  Documentation (this file)
samples/               Example user config templates

📏 Numbering convention¶

Numbered directories (core/, shared_functions/, startup/, hooks/) use 2-digit prefixes so load order is deterministic. Numbers are per-directory (e.g. core/02_vars is first in core; hooks/01_mise is first in hooks).

Even numbers = framework. Odd numbers = reserved for user insertion (e.g. ~/.config/zshand/rc.d/03_my_vars.zsh loads between 02_vars and 04_path). See Override system.

🚀 Boot Sequence¶

zshrc.zsh is the single entry point. It decides how to load (bundle vs individual files), then runs a fixed pipeline. Non-interactive shells (scripts, cron) exit early; interactive shells run the full sequence.

🎯 zshrc.zsh entry point¶

What it is: The one file your ~/.zshrc sources. Typically your .zshrc contains only:

# ~/.zshrc
[[ -f /path/to/zshand/zshrc.zsh ]] && source /path/to/zshand/zshrc.zsh

What it does:

Where it lives: At the framework root, next to setup.zsh. The installer or cloner places the repo and points your .zshrc at zshrc.zsh.

Pipeline (high level)¶

┌─────────────────────────────────────────────────────────────────┐
│                    zshrc.zsh Entry Point                        │
├─────────────────────────────────────────────────────────────────┤
│  0. 🚫 Non-interactive check (early exit for scripts/cron)     │
│  1. 📁 Path & cache initialization                             │
│  2. 🔀 Loading strategy selection (see below)                  │
│  3. 🎨 P10k instant prompt (zero-latency visual)               │
│  4. 🛡️ Safe mode check (emergency recovery)                    │
│  5. ✅ Health validation (system dependencies)                  │
│  6. ⚙️ Core (02→90) + user rc.d/ merged                        │
│  7. 🪨 Hooks (critical sync, then lazy/deferred)                │
│  8. 🔍 Staleness check & optional auto-recompile               │
│  9. 👤 User post.d/ scripts                                    │
│ 10. 📊 Debug summary & cleanup                                 │
└─────────────────────────────────────────────────────────────────┘

🔀 Loading strategies¶

The framework picks the fastest available strategy that matches your environment (e.g. dev mode forces individual files). In production, the full bundle is fastest.

Run echo $ZSHAND_DEV_MODE $ZSHAND_AUTO_FULL. In production with auto-full, one cached file is sourced from $ZSHAND_CACHE_DIR — no build code loaded, no per-dir reads.

📦 Bundle System¶

Why bundles? Sourcing dozens of .zsh files costs time; one pre-compiled file (or one per directory) loads in a single read and parse. The build system concatenates sources (with user overrides merged in), then zcompiles to .zwc bytecode. Result: 3–5× faster load per directory, and with a full bundle the whole framework + your config loads in one shot.

Bundle types¶

How compilation works¶

flowchart LR
  subgraph inputs[" "]
    A[Source files\nframework + user]
  end
  subgraph merge[" "]
    B[Merge by basename\nuser replaces framework]
  end
  subgraph build[" "]
    C[Concatenate\nload order]
    D[one .zsh]
    E[zcompile]
    F[.zwc bytecode]
  end
  A --> B --> C --> D --> E --> F

User files in rc.d/, functions/, widgets/, hooks/ that share a basename with a framework file are replaced in the bundle; unique names are added. See Override system.

Commands¶

If you edit .zsh files and don’t rebuild, the old bytecode is still loaded. You’ll see a “stale” warning at startup. Run zr or zfull (and exec zsh) to refresh.

🔄 Override System¶

You can replace or extend the framework without forking. Same basename in your config = replaces the framework file. Different name = adds (both load). Framework updates never overwrite your config.

Example: To replace the framework’s aliases entirely, add ~/.config/zshand/rc.d/14_aliases.zsh. The loader will use your file instead of $ZSHAND/core/14_aliases.zsh. To add aliases on top, use ~/.config/zshand/aliases.zsh (loaded after core).

Resolution rule¶

Framework:  $ZSHAND/core/14_aliases.zsh
User:       $ZSHAND_CONFIG_DIR/rc.d/14_aliases.zsh   ← wins (same basename)

Same rule applies in functions/, widgets/, hooks/: same basename → replace; new name → add. Full layout: Config.

User config directory¶

~/.config/zshand/                   ($ZSHAND_CONFIG_DIR)
├── env.zsh           🌍 Environment variables (auto-exported)
├── secrets.zsh       🔒 API keys and tokens (chmod 600)
├── aliases.zsh       📝 Custom aliases (loaded after framework)
├── path.txt          🛤️ Additional PATH entries (one per line)
├── config.toml       ⚙️ Framework behavior (dev_mode, quiet, perf_budget, etc.)
├── bin/              📟 Personal scripts (on $PATH)
├── functions/        🛠️ Custom functions (override or extend)
├── widgets/          ⌨️ Custom ZLE widgets
├── hooks/            🪨 Custom tool hooks (e.g. 60_my_tool.zsh)
├── rc.d/             ⚙️ Core overrides (same numbering as core/, e.g. 14_aliases.zsh)
├── init.d/           🚀 Before framework (early scripts)
└── post.d/           🏁 After everything (final tweaks)

User file load order¶

⚙️ Key Subsystems¶

🔧 Engine (core/06_engine.zsh)¶

The engine is the largest core module and the one that makes “rebuild and reload” work. It defines:

• zprime / zr — Compile directories (or full bundle), optionally reload shell
• zrun — Run commands with optional telemetry logging
• _z_system_init — Post-init: Atuin, terminal title, security checks
• Incremental rebuild — Only recompile dirs that changed (or depend on changed dirs)
• Completion generation — Atomic completion for external CLIs

If you’re asking “where does zr come from?” or “who builds the bundle?” — it’s here. See Build System for the full pipeline.

🧱 Shared functions (shared_functions/)¶

Lowest-level primitives, loaded in the same pass as startup/ (alphabetically). No core/ or user code runs before these. Used by startup scripts, init.d, post.d, and rc.d.

Shared Functions has the full list.

🛡️ Safe mode (startup/24_az_safe_mode.zsh)¶

If the shell fails to init 3+ times in a short window (or you set ZSHAND_SAFE_MODE=1), the next start drops into safe mode: minimal PATH, no framework, recovery menu. Lets you fix a broken config without losing shell access. See Safe Mode.

📊 Profiling pipeline¶

ZSHAND_PROFILE_BUNDLE=1 exec zsh   →  instrumented bundle built & run
         ↓
profile-timing.log                 →  raw TYPE|NAME|START|END
         ↓
profile_bundle_report.zsh          →  graded report (A–F, bar charts)

Use when tracking down slow startup. Performance and Profile Report Guide have details.

🪨 Hook classification¶

Hooks (tool integrations) are classified in core/18_hooks.zsh so the loader can run some at once and defer others:

With ZSHAND_LAZY_LOAD=1, non-critical hooks run in a background subshell after 1 second, so startup stays fast. Add your own in ~/.config/zshand/hooks/ (e.g. 60_my_tool.zsh). Full list and ordering: Hooks.

🧪 Testing architecture¶

Tests live under tests/ and spec/ (ShellSpec). Specs mirror the source tree: e.g. functions/dcopy.zsh → spec/functions/dcopy_spec.sh. Run just test (or shellspec). CI uses Kcov for coverage. See Testing.

🌍 Environment variables¶

These control where the framework looks for files, whether to use bundles, and how noisy or strict to be. Set before the framework loads (e.g. in ~/.zshenv for ZSHAND_AUTO_FULL).

Framework controls¶

🔑 XDG Compliance¶

The framework follows the XDG Base Directory Specification:

📐 Dependency graph¶

zshrc.zsh
  ├── shared_functions/*     (first — primitives; no core yet)
  ├── startup/*              (same pass as shared_functions, alphabetical merge)
  ├── [if not bundle] build/detect_dev_mode.zsh
  ├── core/02_vars.zsh       (bootstrap; no other core deps)
  │     → 04_path → 06_engine → 08_audit → 10_options → … → 90_functions
  ├── hooks/*                (after core; order from 18_hooks.zsh)
  ├── P10k theme
  └── post.d/*               (last)

shared_functions/ and startup/ load before any core/. Within core/, files run in numeric order only; a file must not depend on a higher number in the same directory.