Skip to content

🛡️ ZSHAND Safe Mode

Automatic emergency recovery that activates when the shell fails to initialize repeatedly, preventing a broken configuration from locking you out of your terminal.

How It Works

Safe mode monitors a failure tracking file at $ZSHAND_CACHE_DIR/init_failures. Each time shell initialization encounters a critical error, a timestamped entry is appended to this file. If three or more failures occur within a five-minute window, safe mode activates on the next shell start.

When safe mode is active, the framework skips the full initialization sequence and instead loads a minimal environment with a basic PATH, a simple prompt, and a recovery menu.

Triggering Safe Mode

Safe mode can be triggered in two ways.

Automatic detection happens when _az_safe_mode_required finds three or more recent failure entries in the tracking file. This is checked early in zshrc.zsh, before core configs load.

Manual activation is available by setting ZSHAND_SAFE_MODE=1 before starting a shell:

ZSHAND_SAFE_MODE=1 exec zsh

This is useful when you know your config is broken and want to go straight to recovery without waiting for three failures.

What Safe Mode Provides

The safe mode environment includes:

  • A basic PATH (/usr/local/bin:/usr/bin:/bin)
  • A minimal prompt indicating safe mode is active
  • Powerlevel10k instant prompt (if the cache file exists)
  • A recovery menu with actionable repair commands

The recovery menu typically offers options like:

  • View recent error logs
  • Run syntax validation on framework files
  • Force a clean rebuild (zrebuild)
  • Reset to last known good configuration
  • Exit safe mode and retry normal initialization

Clearing Safe Mode

To exit safe mode and return to normal initialization:

  1. Fix the underlying issue (syntax error, missing file, broken dependency)
  2. Delete the failure tracking file: rm -f ~/.cache/zshand/init_failures
  3. Start a new shell: exec zsh

Alternatively, if you used manual activation, simply start a new shell without the environment variable.

Failure Tracking

The failure file is a plain text file with one timestamped line per failure. Only failures within the last five minutes count toward the threshold. Old entries are effectively ignored, so a failure from yesterday won't contribute to triggering safe mode today.

The health validation script (startup/21_az_health_validate_tools.zsh) and the directory integrity check in zshrc.zsh are the primary writers to this file.

Edge Cases

  • Missing failure file: Safe mode is not triggered (no failures recorded).
  • Stale failure file: Only entries less than 5 minutes old count.
  • Cache directory missing: The failure file cannot be written, so automatic safe mode won't trigger — but manual activation still works.
  • Permission issues: If the cache directory is unwritable, failure tracking is silently skipped.

Implementation

Safe mode logic lives in startup/24_az_safe_mode.zsh, which defines three functions:

  • _az_safe_mode_required — checks if safe mode should activate (returns 0 if yes)
  • _az_safe_mode_enter — loads the minimal environment and recovery menu
  • _az_safe_mode_recovery_menu — displays interactive repair options

These are called from zshrc.zsh in Section 3 (Emergency Repair & Safe Mode), before core configs load.

See Also