Skip to content

🚀 ZSHAND Startup Scripts Reference

📋 Bootstrap-only _az_* functions that handle TOML config, keybindings, health checks, safe mode, and other initialization tasks. These are unset after init — they don't persist in your session.

📂 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
📂 startup/README.md In-tree quick reference
🧱 SHARED_FUNCTIONS.md Shared functions (loaded alongside)
🏗️ ARCHITECTURE.md Boot sequence
🔧 TROUBLESHOOTING.md Safe mode recovery