Skip to content

🚀 ZSHAND Startup Scripts Reference

ZSHAND Startup Timeline
Every millisecond accounted for — P10k instant prompt to background recompile in ~47ms

📋 Bootstrap-only _az_* functions that handle TOML config, keybindings, health checks, safe mode, and other initialization tasks. They run in the same load pass as shared_functions (alphabetically merged), then are unset after init so they don't persist in your session.
Pipeline Architecture (boot sequence) · Core (what runs after)
Config Config (config.toml, keybindings) · Safe Mode
Primitives Shared Functions (same pass, persists)
Index Documentation Index

Where startup fits

Startup scripts run before core. See Architecture → Boot sequence for the full pipeline.

When each script runs (by role)

Phase Scripts What they do
Config & bindings 16_az_load_toml_config, 17_az_bindkey_from_toml Parse config.toml → env vars; apply keybindings from TOML
Dev & env 05_az_dev_mode_check, 14_az_vscode_integration, 15_az_wayland_clipboard Dev mode detection; VS Code; Wayland clipboard
Health & safety 21_az_health_validate_tools, 24_az_safe_mode Require git/zsh; failure tracking and safe mode
Theme & notices 23_az_theme_restore_p10k, 22_az_perf_budget_warn, 20_az_debug_timing_summary P10k theme; perf warnings; debug timing
Bundles & cleanup 19_az_zwc_stale_check, 25_az_startup_sentinel, 26_az_create_reference_links Stale check; zprime status; convenience symlinks

Load order is merged alphabetically with shared_functions (see Merged Load Order below).

📂 Script Reference

File Function Purpose
05_az_dev_mode_check.zsh _az_dev_mode_check Detect dev mode (.dev file or dirty git)
14_az_vscode_integration.zsh _az_vscode_integration VS Code terminal integration
15_az_wayland_clipboard.zsh _az_wayland_clipboard Wayland clipboard setup
16_az_load_toml_config.zsh _az_load_toml_config Parse config.toml → env vars
17_az_bindkey_from_toml.zsh _az_bindkey_from_toml Apply keybindings from TOML
19_az_zwc_stale_check.zsh _az_zwc_stale_check Set needs_recompile flag
20_az_debug_timing_summary.zsh _az_debug_timing_summary Init timing report
21_az_health_validate_tools.zsh _az_health_validate_tools Require git, zsh, etc.
22_az_perf_budget_warn.zsh _az_perf_budget_warn Warn when files exceed budget
23_az_theme_restore_p10k.zsh _az_theme_restore_p10k Source .p10k.zsh theme
24_az_safe_mode.zsh _az_safe_mode_* Failure detection and recovery
25_az_startup_sentinel.zsh _az_startup_sentinel zprime status check
26_az_create_reference_links.zsh _az_create_reference_links Create convenience symlinks

🔄 Load Behavior

  • Loaded together with shared_functions/ in one alphabetical pass
  • Numbering (05–26) interleaves with shared_functions (01–18) for correct order
  • All _az_* functions are unset at the end of zshrc.zsh to save memory
  • Shared functions (no _az_ prefix) persist for the session

📊 Merged Load Order

01_stderr_error.zsh        (shared_functions — persists)
02_stderr_warn.zsh         (shared_functions — persists)
03_init_log_append.zsh     (shared_functions — persists)
04_echo_info.zsh           (shared_functions — persists)
05_az_dev_mode_check.zsh   (startup — unset after init)
05_echo_ok.zsh             (shared_functions — persists)
06_time_millis.zsh         (shared_functions — persists)
...
16_az_load_toml_config.zsh (startup — unset after init)
16_zrun.zsh                (shared_functions — persists)
17_az_bindkey_from_toml.zsh(startup — unset after init)
17_clipboard_copy.zsh      (shared_functions — persists)
...
26_az_create_reference_links.zsh (startup — unset after init)

📏 Key Scripts

16_az_load_toml_config.zsh — TOML Config Parser

Parses ~/.config/zshand/config.toml and exports values as ZSHAND_* environment variables. Called early by core/02_vars.zsh.

17_az_bindkey_from_toml.zsh — Keybinding Loader

Reads [keybindings] section from config.toml and applies bindkey commands. Called by core/16_widgets.zsh.

24_az_safe_mode.zsh — Safe Mode

Tracks startup failures. After multiple consecutive crashes, safe mode activates automatically, providing a minimal recovery shell.

19_az_zwc_stale_check.zsh — Stale Check

Compares .zwc bundle timestamps against source files. Sets needs_recompile flag for zprime to act on.

Document Purpose
🏗️ Architecture Boot sequence and loading strategies
⚙️ Core What runs after startup (02_vars → 90_functions)
🧱 Shared Functions Primitives loaded in the same pass as startup
🛡️ Safe Mode Recovery (triggered by 24_az_safe_mode.zsh)
📂 Config config.toml and keybindings
📡 API / Source Per-file generated docs (e.g. startup scripts)
📚 Documentation Index Full doc nav