ZSHRC Latest Changes

This document tracks all significant changes to ~/.zshrc and why they were made, so developers and AI agents can understand the rationale and avoid re-introducing old problems.

Index of all zsh docs: README.md

Change 5: Yarn script picker (yserve / yscripts) (March 22, 2026)

Goal

Fast, workspace-accurate selection of yarn <script> entries (especially serve:*) via fzf + package.json, without changing history, Ctrl+R, or arrow bindings.

What was added

• Repo: tools/scripts/system/zsh-yarn-scripts-fzf.zsh — functions yarn_scripts_fzf, yarn_serve_scripts_fzf; aliases yserve, yscripts.
• ~/.zshrc: guarded source between --YARN_SCRIPTS_FZF_BEGIN-- and --YARN_SCRIPTS_FZF_END-- (uses GSPACE1_ROOT).

Revert

Remove or comment out that entire ~/.zshrc block. Doc: yarn-scripts-fzf.md.

Safety

Additive only; if the file is missing, nothing loads. Requires fzf and jq or node.

Change 4: compinit / _brew on Apple Silicon (March 22, 2026)

Problem

On startup:

compinit:527: no such file or directory: /usr/local/share/zsh/site-functions/_brew

macOS default fpath often includes /usr/local/share/zsh/site-functions. compinit scans every fpath entry. Homebrew on Apple Silicon installs _brew under /opt/homebrew/share/zsh/site-functions, not /usr/local. Deleting ~/.zcompdump alone does not fix this — fpath still lists the empty/wrong directory.

Solution

Before autoload compinit / compinit, remove the stale directory when Intel _brew is absent and /opt/homebrew completions exist:

if [[ -d /opt/homebrew/share/zsh/site-functions ]] && [[ ! -r /usr/local/share/zsh/site-functions/_brew ]]; then
  fpath=(${fpath:#/usr/local/share/zsh/site-functions})
fi

Verification

zsh -i -c 'exit' 2>&1 | grep -E 'compinit|_brew' || echo "OK"

For AI agents

Do not tell users only to rm ~/.zcompdump for this error — check fpath and _brew location first.

Change 3: Session history directory (March 22, 2026)

Goal

Stop writing per-session history blobs as ~/.zsh_history_* in $HOME root; use ~/.zsh/history/ (via ZSH_HISTORY_DIR) so Finder/ls -a ~ stays readable.

Split model (actual ~/.zshrc layout)

• HISTFILE=$HOME/.zsh_history — zsh’s main history file (SHARE_HISTORY, fc -l, Ctrl+R, etc.).
• SESSION_HISTFILE=$ZSH_HISTORY_DIR/.zsh_history_<timestamp>_<pid> — per-session sidecar (session header line + any tooling that aggregates with sas).
• Both are intentional; only the session blobs moved off $HOME root.

Repo support

• Spec: zsh-history-directory-migration-spec.md
• One-time move: tools/scripts/system/migrate-zsh-history-directory.sh
• Snippet for .zshrc: tools/scripts/system/zsh-history-path.snippet.zsh

.zshrc edits required

1. Define ZSH_STATE_DIR / ZSH_HISTORY_DIR, mkdir -p, then set SESSION_HISTFILE under $ZSH_HISTORY_DIR (keep HISTFILE as $HOME/.zsh_history unless you deliberately switch to a single-file model).
2. In cleanup_session_histories / smart_cleanup_histories, change the glob from "$HOME"/.zsh_history_*(.N) to "$ZSH_HISTORY_DIR"/.zsh_history_*(.N).
3. Update search_all_sessions (sas), csh, si (or any helper) that referenced ~/.zsh_history_* in $HOME to use "$ZSH_HISTORY_DIR"/.zsh_history_*(N) plus $HOME/.zsh_history where appropriate.

Glob reminder (still valid)

Never use find "$HOME" for these files. Always a single-directory glob on $ZSH_HISTORY_DIR (or during migration, optionally both locations once).

Change 2: History Cleanup Performance Fix (February 6, 2026)

Problem

System load was spiking to 40+ (on a machine with ~12 cores) every time multiple terminal sessions started. The root cause was the smart_cleanup_histories function in ~/.zshrc.

Symptoms:

• ps aux showed 10-20+ find processes all consuming 40-57% CPU each
• System load average would jump from ~5 to 35-45
• The find processes would scan the entire home directory recursively
• Every new shell (terminal tab, Cursor shell, background shell) spawned MORE processes
• Killing them didn't help - they'd respawn on the next shell init

Root Cause Analysis

The old implementation had three critical flaws:

Flaw 1: Recursive find on entire $HOME

# OLD (BAD) - scans millions of files recursively
find "$HOME" -name ".zsh_history_*" -type f -mtime +30

The .zsh_history_* files all live directly in $HOME (not in subdirectories), but find was recursively traversing the entire home directory tree including node_modules, .git, application caches, and more. On a developer machine with monorepos, this means scanning millions of files just to find ~2,800 history files that are all in one flat directory.

Flaw 2: Double scan

The cleanup_session_histories function ran find twice:

1. Once to count files (find ... | wc -l)
2. Once to delete them (find ... -delete)

Each invocation was a full recursive scan of $HOME.

Flaw 3: No concurrency protection

The smart_cleanup_histories function used a date-based marker file to run "once per day," but:

• Multiple shells starting simultaneously would ALL read the marker before any wrote it
• Each shell would spawn its own pair of find processes
• Opening 10 terminal tabs = 20 find processes fighting for disk I/O

Solution

The function was rewritten with three corresponding fixes:

Fix 1: Zsh glob instead of recursive find

# NEW (GOOD) - instant, only matches files in $HOME root
for f in "$HOME"/.zsh_history_*(.N); do

The (.N) is a zsh glob qualifier: . matches regular files only, N enables nullglob (no error if no matches). This is instant because it only reads the directory listing of $HOME instead of recursing into every subdirectory.

Fix 2: Single-pass delete

# Check age with stat, delete inline - one loop, no second scan
if [[ $(( $(date +%s) - $(stat -f %m "$f") )) -gt 2592000 ]]; then
    rm -f "$f" 2>/dev/null
    ((count++))
fi

Fix 3: Atomic lock with mkdir

# mkdir is atomic on POSIX - only ONE shell wins the race
if ! mkdir "$cleanup_lock" 2>/dev/null; then
    return 0  # Another shell is already running cleanup
fi
trap "rmdir '$cleanup_lock' 2>/dev/null" EXIT INT TERM

mkdir is an atomic filesystem operation. If the directory already exists, it fails. This guarantees that no matter how many shells start simultaneously, only one will ever run the cleanup. The trap ensures the lock is released even if the process is interrupted.

Performance Impact

Stress Test Results

10 concurrent shells launched → 0 find processes spawned
Marker file written correctly by exactly 1 shell
Lock released cleanly

Files Modified

• ~/.zshrc lines ~472-523: Rewrote cleanup_session_histories and smart_cleanup_histories
• ~/.zshrc line ~656: Re-enabled (smart_cleanup_histories &) (was temporarily disabled during debugging)

For AI Agents

If you see high system load and find processes scanning for .zsh_history_*, check:

1. Has someone reverted ~/.zshrc to the old version?
2. Is the ~/.zsh_cleanup_lock directory stuck (stale lock)? Remove it with rmdir ~/.zsh_cleanup_lock
3. Run pkill -9 -f "find.*zsh_history" as an immediate fix, then verify the .zshrc functions are correct

Never use find "$HOME" to search for these files. Always use a glob on the history directory, e.g. $ZSH_HISTORY_DIR/.zsh_history_* (see Change 3); legacy: $HOME/.zsh_history_*

Change 1: Shell Startup Timeout Fix (November 14, 2025)

Problem

Cursor shows this error when reopening:

Unable to resolve your shell environment in a reasonable time. 
Please review your shell configuration and restart.

This happens because Cursor has a timeout for shell initialization (typically 5-10 seconds). If your .zshrc takes longer than this to load, Cursor will show this error.

Root Causes

The main culprits in your .zshrc were:

1. Nx Completion Setup - Running npx nx completion zsh on every shell startup

   • This command can take 5-15 seconds as it needs to:
     • Execute npx (may download packages)
     • Run Node.js
     • Generate completion scripts

2. Angular CLI Completion - Similar issue with ng completion script

3. Project Environment Setup - Running completion setup immediately on shell start

4. fnm Initialization - Fast Node Manager initialization could add overhead

Solution Applied

1. Lazy-Loaded Completions

Completions are now NOT loaded on shell startup. They only load when you manually call:

• setup_nx_completion (for Nx workspaces)
• setup_ng_completion (for Angular projects)

Benefits:

• Shell starts instantly
• No blocking operations during initialization
• Completions still work when needed (just load them manually)

Trade-off:

• Completions won't be available until you manually load them
• This is acceptable since shell startup speed is more important

2. Optimized fnm Initialization

fnm now only initializes if not already initialized:

if [[ -z "$FNM_DIR" ]]; then
  eval "$(fnm env --use-on-cd 2>/dev/null)" || true
fi

3. Removed Blocking Operations

All slow operations have been removed from the startup path:

• ✅ No npx commands on startup
• ✅ No completion generation on startup
• ✅ No blocking file system operations
• ✅ Background processes properly disowned

How to Use

Manual Completion Loading

If you need completions, simply run:

# For Nx workspaces
setup_nx_completion

# For Angular projects  
setup_ng_completion

These functions are idempotent - they check if already loaded and skip if done.

Verify Shell Startup Speed

Test your shell startup time:

# Time your shell startup
time zsh -i -c exit

Should be under 1 second now (previously could be 5-15 seconds).

Additional Optimizations

If You Still Experience Timeouts

1. Check for other slow operations:

   # Profile your .zshrc
   zsh -x -c exit 2>&1 | grep -E "^\+\+.*seconds|^\+\+.*ms"
   

2. Look for:

   • Network calls (API requests, git fetch, etc.)
   • Large file operations
   • Heavy plugin loading
   • Synchronous package manager operations

3. Common slow operations to defer:

   • Git status checks
   • Package manager updates
   • Cloud SDK initialization
   • Heavy theme/prompt loading

Cursor-Specific Settings

You can also configure Cursor to be more patient:

1. Open Cursor Settings
2. Search for "shell timeout" or "terminal timeout"
3. Increase the timeout value (if available)

However, it's better to fix the root cause (slow shell startup) rather than increase timeouts.

Best Practices

✅ DO:

• Keep shell startup fast (< 1 second)
• Lazy-load heavy operations
• Use background processes for non-critical setup
• Check if tools are already initialized before re-initializing

❌ DON'T:

• Run npx or npm commands on startup
• Make network calls during shell initialization
• Load heavy plugins synchronously
• Run completion generation on every shell start

Verification

After applying these changes:

1. Restart Cursor completely
2. Open a new terminal - should start instantly
3. Check for the timeout error - should be gone
4. Test completions - manually load if needed

Summary

The key insight: Shell startup must be fast. Anything that takes more than 1-2 seconds should be:

• Lazy-loaded (only when needed)
• Run in background
• Deferred until after shell is ready

Your shell is now optimized for fast startup while maintaining all functionality when needed.