🪨 ZSHAND Hooks Guide¶

📋 Hooks integrate external tools (mise, Atuin, Docker, etc.) into the shell. They're classified as critical (sync) or lazy (deferred) to keep startup fast.

🔄 How Hooks Work¶

Hooks are zsh scripts in hooks/ that initialize third-party tools. Each hook:

1. Guards — checks if the tool is installed ($+commands[tool])
2. Initializes — runs eval "$(tool init zsh)" or equivalent
3. Configures — sets tool-specific options or aliases

⚡ Critical vs 🕐 Lazy¶

The framework classifies hooks into two tiers (defined in core/18_hooks.zsh):

Lazy loading is enabled with ZSHAND_LAZY_LOAD=1 and moves 20–80ms of hook loading out of the startup path.

📂 Framework Hooks¶

🔢 Numbering Ranges¶

✏️ Writing a Custom Hook¶

Place custom hooks in ~/.config/zshand/hooks/:

# ~/.config/zshand/hooks/35_my_tool.zsh

# Guard: only load if tool exists
(( $+commands[my_tool] )) || return 0

# Initialize
eval "$(my_tool init zsh)"

# Optional: configure
export MY_TOOL_CONFIG="value"

📏 Hook Pattern¶

Every hook should follow this structure:

# 1. Guard clause (skip if tool not installed)
(( $+commands[tool_name] )) || return 0

# 2. Cached activation (if supported)
local cache_file="$ZSHAND_CACHE_DIR/tool_name_init.zsh"
if [[ ! -f "$cache_file" || "$cache_file" -ot "$(command -v tool_name)" ]]; then
    tool_name init zsh > "$cache_file"
fi
source "$cache_file"

# 3. Tool-specific configuration
export TOOL_OPTION="value"
alias tl='tool_name list'

⚡ Performance Tips¶

• Cache activation output — eval "$(tool init zsh)" spawns a subprocess every startup. Cache the output to a file instead.
• Use return 0 not return 1 — a non-zero return from a hook stops the loading chain.
• No network calls — hooks run during startup. Defer network to background.
• Pick the right number — critical tools get 01–09, everything else 20+.

🔀 Override Behavior¶

User hooks with the same basename as framework hooks replace them:

~/.config/zshand/hooks/01_mise.zsh  →  replaces $ZSHAND/hooks/01_mise.zsh
~/.config/zshand/hooks/60_custom.zsh  →  added (no framework equivalent)

User hooks with unique basenames are loaded alongside framework hooks, sorted by number.

🧪 Testing Hooks¶

# Check if a hook's tool is detected
(( $+commands[mise] )) && echo "mise found"

# Test a hook in isolation
ZSHAND_DEBUG=1 source hooks/01_mise.zsh

# Check hook timing
ZSHAND_PROFILE_BUNDLE=1 exec zsh
# → Look for hooks section in the profile report

# Verify lazy vs critical classification
grep -A5 'critical\|lazy' core/18_hooks.zsh

🔗 Related Documents¶