Enhanced Zsh System

Modern development tools, improved history management, and seamless integration with Cursor and VS Code

Enhanced Zsh System Documentation

🚀 Overview

Your Zsh system has been significantly enhanced with modern development tools, improved history management, and seamless integration with Cursor and VS Code. The npm warning has been fixed, and you now have a powerful, intuitive command-line environment.

✅ Issues Fixed

1. NPM Warning Resolution

2. Enhanced History Search

🛠️ New Tools Installed

Core Modern Tools

Zsh Enhancements

🎨 Beautiful Prompt

Your new Starship prompt shows:

🔧 Enhanced Commands

Navigation & Search

File Operations

Development Shortcuts

# Git (Enhanced)
gs          # git status --short (clean output)
ga          # git add
gc          # git commit
gp          # git push
gl          # git log --oneline --graph --decorate
gd          # git diff
gb          # git branch
gco         # git checkout
gf          # git fetch
gm          # git merge

# Yarn/NPM
y           # yarn
yi          # yarn install
ya          # yarn add
yr          # yarn remove
ys          # yarn start
yb          # yarn build
yd          # yarn dev
# Optional (gspace1 zsh-yarn-scripts-fzf — see docs/english/Developers/zsh/yarn-scripts-fzf.md)
yserve      # fzf pick a yarn script (starts with query serve:)
yscripts    # fzf pick any script from ./package.json

# Nx (Enhanced)
nx          # npx nx
nxg         # npx nx generate
nxs         # npx nx serve
nxb         # npx nx build
nxt         # npx nx test
nxl         # npx nx lint
nxr         # npx nx run
nxc         # npx nx reset (clear cache)
nxgraph     # npx nx graph (view dependency graph)

# Cursor/VS Code Integration
cursor      # Open in Cursor
c           # Short alias for Cursor
c.          # Open current directory in Cursor
code        # Open in VS Code
vs          # Short alias for VS Code
vs.         # Open current directory in VS Code

Analysis & Maintenance

si          # Show detailed session information
tc [N]      # Show top N most used commands (default: 10)
sysinfo     # Show comprehensive system information
sas [term]  # Search all session histories (interactive if no term)
csh         # Clean old session files
?           # Show help for all enhanced commands
ah-help     # Show advanced history navigation help
advanced-history-help  # Detailed help for fuzzy navigation

Utility Functions

mkcd dir    # Create directory and cd into it
proj name   # Navigate to project (fuzzy search if no name)
edit file   # Edit file in Cursor (fuzzy search if no file)

⌨️ Key Bindings

History & Search

Navigation

🔄 Smart Features

Auto-Detection

Performance Optimizations

Smart History Cleanup (Updated February 2026)

The smart_cleanup_histories function runs once per day in the background to delete .zsh_history_* files older than 30 days. It is designed to be safe with many concurrent shells:

How it works:

  1. On shell startup, (smart_cleanup_histories &) runs in background
  2. Function reads ~/.zsh_cleanup_marker - if today's date, returns immediately (fast path)
  3. If cleanup needed, attempts mkdir ~/.zsh_cleanup_lock - atomic, only one shell wins
  4. Winner iterates session history files via zsh glob (instant, no recursion) — prefer $ZSH_HISTORY_DIR/.zsh_history_*(.N) when using the layout in zsh-history-directory-migration-spec.md; legacy setups used $HOME/.zsh_history_* in the home root
  5. Deletes files older than 30 days, writes today's date to marker, releases lock
  6. All other concurrent shells see the lock exists and silently skip

Key design decisions:

Troubleshooting:

🎯 Cursor/VS Code Integration

Project Auto-Opening

Create a .cursor-auto file in any project to automatically open it in Cursor when you cd into it:

touch .cursor-auto

Fuzzy File Opening

📊 Session Management

Enhanced History

Session Information

The si command shows:

🚀 Getting Started

Quick Start Commands

?           # Show all available commands
si          # Check your session info
tc          # See your most used commands
cf          # Try fuzzy file search
proj        # Navigate to a project

Learning the New Features

  1. Advanced History Navigation: Start typing any command, then use up/down arrows to cycle through ALL matching commands from your history
  2. Real-time Filtering: Every letter you type instantly narrows down the matches - no need to open Ctrl+R
  3. Multiple Match Navigation: Unlike basic autosuggestions, you can now see and navigate through multiple matching commands
  4. Fuzzy Search Integration: The same powerful fuzzy matching from Ctrl+R is now built into regular typing
  5. File Navigation: Use cf to fuzzy-search and open files
  6. Project Navigation: Use proj to quickly jump between projects
  7. Enhanced Listings: Try ll to see the beautiful file listing
  8. Help System: Type ? whenever you need a reminder

📚 Documentation index (repo)

For changelog-style ~/.zshrc decisions (history directory, cleanup, Apple Silicon compinit), see docs/english/Developers/zsh/README.md and zshrc-latest-changes.md. Session history layout: zsh-history-directory-migration-spec.md.

🔧 Configuration Files

Main Configuration

Installation & Testing

Backup

🚀 Installation of Advanced History Navigation

Option 1: Automated Installation (Recommended)

Run the provided installation script:

cd apps/docs-angular/src/assets/docs/development/
./install-advanced-history.sh

The script will:

Option 2: Manual Installation

To manually add the enhanced up/down arrow navigation:

Step 1: Add to your .zshrc

Add this line to your ~/.zshrc file:

# Source advanced history navigation
source "/path/to/zsh-advanced-history.zsh"

Step 2: Reload ZSH

source ~/.zshrc
# OR restart your terminal

Testing the New Functionality

You can run the automated test script to verify everything is working:

./test-advanced-history.sh

Or test manually:

# Type part of a command you've used before
git ch

# Press Up arrow to cycle through all matching commands
# Each press shows the next match with [n/total] indicator

# Try adding more letters to refine the search
git che
# Now Up arrow only shows commands matching "git che"

🔍 Advanced History Navigation

How It Works

The enhanced up/down arrow navigation transforms your command line into a powerful search interface:

Example Workflow

# Type the beginning of a command
$ git ch

# Press Up Arrow - cycles through ALL commands that contain "git ch":
$ git checkout main           # ← First match
$ git cherry-pick abc123      # ← Second match (press Up again)  
$ git checkout develop        # ← Third match (press Up again)
$ git check-ignore file.txt   # ← Fourth match (press Up again)

# Add more letters to narrow down
$ git chec

# Now only shows commands matching "git chec":
$ git checkout main           # ← Matches "git chec"
$ git check-ignore file.txt   # ← Also matches "git chec"

Key Features

Comparison: Before vs After

Before (Basic History Search):

After (Advanced Fuzzy Navigation):

💡 Tips & Best Practices

For Cursor Users

For Development

For Productivity

🎉 What's Different

Before (Basic ZSH)

fguijarro@gograbscstudio3 editor % ls
# Basic listing
npm warn Unknown project config "max_old_space_size"
# Limited history search - only one suggestion
# Up arrow shows one recent command starting with typed text
$ git ch[UP] → git checkout main (only one option)

After (Enhanced ZSH with Advanced Navigation)

🍎 fguijarro  …/editor   unified-nav-4 $!?   v22.15.0   10:07  
➜ ll
# Beautiful colored listing with git status
# No npm warnings
# Advanced fuzzy navigation built-in

# Type and navigate through ALL matching commands:
$ git ch[UP] → git checkout main      [1/4] ← Shows match counter
$ git ch[UP] → git cherry-pick abc123 [2/4] ← Next match  
$ git ch[UP] → git check-ignore file  [3/4] ← Another match
$ git ch[UP] → git checkout develop   [4/4] ← All matches available

# Every letter refines the search:
$ git che[UP] → git checkout main     [1/2] ← Fewer matches
$ git che[UP] → git check-ignore file [2/2] ← Only relevant matches

🌟 Next Steps

  1. Explore: Try each new command to get familiar
  2. Customize: Modify the Starship prompt colors in ~/.config/starship.toml
  3. Integrate: Add .cursor-auto files to your favorite projects
  4. Share: These configurations can be shared across your development team

🔧 Troubleshooting Advanced History Navigation

compinit: ... /usr/local/.../_brew (Apple Silicon)

macOS often puts /usr/local/share/zsh/site-functions on fpath, but Homebrew’s _brew lives under /opt/homebrew. rm ~/.zcompdump alone may not fix it. See Change 4 in zshrc-latest-changes.md (prune fpath before compinit).

Note: ls -lt ~/.zsh/history may break if ls is aliased to eza (-t means something else). Use command ls -lt ~/.zsh/history or eza --sort=modified ~/.zsh/history.

Common Issues

Up/Down arrows not working as expected

No matches found when typing

Match counter not showing

Performance issues with large history

Manual Testing

# Test if the widgets are loaded
zle -l | grep advanced-history

# Test key bindings
bindkey | grep advanced-history

# View current history size
fc -l | wc -l

# Test manual search
fc -ln 1 | grep -i "your-search-term" | head -10

Reverting Changes

If you need to disable the advanced navigation:

# Comment out the source line in .zshrc
sed -i 's/^source.*zsh-advanced-history.zsh/#&/' ~/.zshrc
source ~/.zshrc

Getting Help

Your terminal is now a powerful, modern development environment optimized for productivity and seamlessly integrated with Cursor and VS Code!