Skip to content

⚡ ZSHAND Performance Guide

📋 This guide covers performance targets, how to profile, how to read reports, and optimization strategies for keeping shell startup fast.

🧠 Philosophy

Every millisecond counts at startup. The framework targets <50ms cold start and <10ms warm start. Profile before optimizing — gut feelings about performance are almost always wrong.

Run a profiled shell and see a graded report (which files are slow):

ZSHAND_PROFILE_BUNDLE=1 exec zsh

Or use zprofile for more options (zprofile --full, zprofile --report). See Profile Report Guide to read the report.

Measure cold start time (e.g. before/after a change):

hyperfine --warmup 3 'zsh -ic exit'

Use a full bundle so one file loads instead of dozens: set ZSHAND_AUTO_FULL=1 in ~/.zshenv, or run zfull. Enable lazy hooks with ZSHAND_LAZY_LOAD=1 to defer non-critical tools. See Optimization strategies below.

🎯 Performance Targets

Metric Target Grade A Grade F How to Measure
⚡ Cold start <50ms <50ms ≥500ms hyperfine 'zsh -ic exit'
⚡ Warm start (P10k) <10ms <10ms >100ms Instant prompt to interactive
📊 Per-file budget <100ms <50ms ≥200ms ZSHAND_PERF_BUDGET enforcement
📦 Bundle load <30ms <20ms >100ms Profile bundle report
🪨 Hook total <50ms <30ms >150ms Profile bundle report

⭐ Grading Scale

The framework uses letter grades for performance reports:

Grade Stars Threshold Meaning
A ★★★★ <50ms Excellent — near-instant
A- ★★★☆ <100ms Great — barely perceptible
B ★★★ <150ms Good — fast enough
B- ★★☆ <200ms Acceptable — room for improvement
C ★★ <250ms Mediocre — optimize
C- ★☆ <350ms Slow — deferred loading recommended
D ★ <500ms Poor — significant work needed
F ≥500ms Failing — major issues

📊 Profiling Pipeline

🔄 Overview

ZSHAND_PROFILE_BUNDLE=1 exec zsh     ← Start profiled shell
        │
        ▼
compile_profile_bundle.zsh            ← Builds instrumented bundle
        │
        ▼
$ZSHAND_CACHE_DIR/profile-timing.log  ← Raw timing data
        │
        ▼
profile_bundle_report.zsh            ← Generates graded report
        │
        ▼
Terminal: color-coded report          ← Grades, bar charts, bottlenecks

▶️ Running a Profile

# Quick profile (shows report immediately)
ZSHAND_PROFILE_BUNDLE=1 exec zsh

# Full profile (includes widget profiling, deferred/lazy timing)
zprofile --full

# Profile and defer report (captures deferred hook data)
zprofile --report
# → Use the profiled shell normally for a few seconds
# → Exit the shell → report displays with deferred/lazy data included

📖 Reading the Report

The profile report shows timing data organized by directory:

⚡ ZSHAND Profile Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Total startup: 42.3ms  Grade: A  ★★★★

📂 Directory Breakdown:
  shared_functions   3.2ms  ▓░░░░░░░░░   7.6%
  startup            4.1ms  ▓░░░░░░░░░   9.7%
  core              18.7ms  ▓▓▓▓▓░░░░░  44.2%
  functions          5.3ms  ▓▓░░░░░░░░  12.5%
  widgets            2.1ms  ▓░░░░░░░░░   5.0%
  hooks              8.9ms  ▓▓▓░░░░░░░  21.0%

🐌 Slowest Files:
  core/06_engine.zsh        8.4ms  ← Engine init (Atuin, security)
  core/20_plugins.zsh       5.2ms  ← Plugin loading
  hooks/01_mise.zsh         4.1ms  ← Runtime manager init

⚡ Deferred Operations:
  hooks/20_docker.zsh       12ms   (deferred — not in startup path)
  hooks/50_gitid.zsh         8ms   (deferred — loaded after 1s)

Key things to look for:

  • 🔴 Any single file >20ms → candidate for optimization
  • 🔴 Total >100ms → investigate top 3 slowest files
  • 🟡 Deferred items >50ms → consider if they need to load at all
  • 🟢 Total <50ms → you're in great shape

🔧 Optimization Strategies

1️⃣ Use Compiled Bundles

The single biggest performance win. Instead of sourcing 50+ individual files, source one pre-compiled bundle:

# Compile everything into a single bundle
zprime --full

# Enable auto-full mode (compiles on first run, then loads bundle)
export ZSHAND_AUTO_FULL=1

Impact: Individual files ~200ms → Full bundle ~30ms (6–7x faster)

2️⃣ Defer Non-Critical Hooks

Hooks that aren't needed at first prompt can load after a 1-second delay:

# Enable lazy loading
export ZSHAND_LAZY_LOAD=1

Hook classification is defined in core/18_hooks.zsh:

  • ⚡ Critical (sync): 01_mise, 02_atuin, 05_ssh-agent
  • 🕐 Lazy (deferred): 20_docker, 30_zoxide, 50_gitid, etc.

Impact: Moves 20–80ms of hook loading out of the startup path.

3️⃣ Cache Expensive Operations

Pattern Example Savings
🗂️ Cache command output mise activate → cached .zsh file ~15ms
🗂️ Cache network state Ping check → 5-min TTL file ~50ms
🗂️ Cache completions gh completion → cached file ~20ms
🗂️ Bytecode compile .zsh → .zwc via zcompile ~5ms per file

4️⃣ Use Zsh Builtins Over External Commands

Slow (subprocess) Fast (builtin) Savings
$(date +%s%N) $EPOCHREALTIME ~3ms
$(wc -l < file) ${#${(f)"$(<file)"}} ~2ms
$(basename "$path") ${path:t} ~2ms
$(dirname "$path") ${path:h} ~2ms
$(stat -c %s file) zstat -H arr file ~2ms
$(hostname -s) ${HOST%%.*} ~2ms
if [ -d "$dir" ] [[ -d "$dir" ]] <1ms

5️⃣ Avoid Network in Startup Path

Network calls are the #1 cause of slow startup:

  • 🚫 Never curl/wget during init
  • 🚫 Never ping synchronously (cache the result)
  • 🚫 Never git fetch during startup
  • ✅ Defer network ops to background or hooks
  • ✅ Cache network state with TTL ($ZSHAND_CACHE_DIR/network_state)

6️⃣ Profile Exceptions

Some files are inherently slow (e.g., plugin managers). Add them to config/profile-exceptions.conf to suppress warnings:

# pattern | max_time_ms | reason
20_plugins.zsh | 15 | Plugin loading is inherently slow
01_mise.zsh    | 10 | Runtime manager activation

📏 Benchmarking

# Basic startup benchmark (3-run warmup, 10 runs)
hyperfine --warmup 3 'zsh -ic exit'

# Compare two configurations
hyperfine --warmup 3 \
  'ZSHAND_AUTO_FULL=1 zsh -ic exit' \
  'ZSHAND_DEV_MODE=1 zsh -ic exit'

# Export for comparison across commits
hyperfine --warmup 3 'zsh -ic exit' --export-json bench.json

# Single file load time
hyperfine --warmup 3 'zsh -c "source core/06_engine.zsh"'

🔍 Debug Timing

# Enable debug mode with per-file timing
ZSHAND_DEBUG=1 ZSHAND_TIMING_DETAIL=1 exec zsh

# Output shows per-file and per-directory timings:
#   ⏱  shared_functions: 3.2ms (18 files)
#   ⏱  core: 18.7ms (11 files)
#     → core/06_engine.zsh: 8.4ms  ⚠️ OVER BUDGET
#   ⏱  hooks: 8.9ms (9 files)

📊 CI Regression Detection

# In CI pipeline:
hyperfine --warmup 3 --min-runs 10 'zsh -ic exit' --export-json current.json

# Compare against baseline (fail if >10ms regression)
# (custom script or manual comparison)

🐌 Common Bottlenecks

Bottleneck Typical Cost Fix
🔌 Plugin loading (oh-my-zsh) 30–100ms Bundle plugins, use ZSHAND_AUTO_FULL
🪨 mise/nvm/pyenv activation 10–30ms Cache activation output
🔒 Atuin daemon start 5–20ms Background start with readiness loop
📝 Completion generation 10–50ms Cache completions, generate lazily
📂 Glob expansion (many files) 5–15ms Reduce glob scope, use (N) nullglob
🔍 Command existence checks 1–3ms each Batch checks, cache results
🌐 Network checks 50–500ms Never in startup — cache with TTL

🔄 Continuous Monitoring

📋 Regular Checks

# Weekly: Full profile to catch regressions
zprofile --full

# After changes: Quick benchmark
hyperfine --warmup 3 'zsh -ic exit'

# After adding hooks/plugins: Check hook timing
ZSHAND_DEBUG=1 exec zsh

⚠️ Warning Signs

  • 🔴 Startup >100ms → Profile immediately
  • 🔴 Single file >50ms → Investigate and optimize
  • 🟡 New hook >10ms → Consider deferring
  • 🟡 Grade dropped → Compare with previous profile

Next: Profile Report Guide (how to read the report) · Architecture (loading strategies) · Build System (zprofile, compile commands)

Next: Profile Report Guide (how to read the report) · Architecture (loading strategies) · Build System (zprofile, compile commands)

Document Purpose
📊 Profile Report Guide How to read the graded profile output in detail
🏗️ Architecture Bundle system and loading strategies
⚡ Auto-Full Mode Fast path with a single compiled bundle
🏗️ Build System Compilation commands and profiling bundle
📐 Header Standard PERFORMANCE section in source headers
📚 Documentation Index Full doc nav