Navigating through deeply nested project directories can slow down your daily workflow. While external tools exist to help jump around directories, you can easily build your own lightweight, robust solution right inside Zsh using a custom function and a simple text file.

The Complete Implementation

Below is the complete implementation of the custom script, saved as ~/scripts/cd_shortcuts.sh. It handles keyword shortcuts, duplicate checks, tab autocomplete, and preserves standard relative navigation like cd ..:

# Path to store your shortcuts
SHORTCUTS_FILE="$HOME/.cd_shortcuts.txt"
touch "$SHORTCUTS_FILE"

_custom_cd_logic() {
    case "$1" in
        "-h"|"--help")
            echo "Usage:"
            echo "  cd <shortcut>                -> Jump to a saved directory"
            echo "  cd -add <name of keyword>    -> Save current directory as a shortcut"
            echo ""
            echo "Available cd shortcuts:"
            echo "-----------------------"
            if [ ! -s "$SHORTCUTS_FILE" ]; then
                echo "No shortcuts added yet. Use 'cd -add <name>' to add one."
            else
                while IFS='=' read -r key val; do
                    printf "%-10s -> %s\n" "$key" "$val"
                done < "$SHORTCUTS_FILE"
            fi
            ;;
        "-add")
            if [ -z "$2" ]; then
                echo "❌ Please provide a name. Usage: cd -add <keyword>"
                return 1
            fi
            # Remove existing shortcut with the same name if it exists (cross-platform safe)
            sed -i "" "/^$2=/d" "$SHORTCUTS_FILE" 2>/dev/null || sed -i "/^$2=/d" "$SHORTCUTS_FILE"
            # Append the new shortcut (keyword=current_working_directory)
            echo "$2=$PWD" >> "$SHORTCUTS_FILE"
            echo "✅ Shortcut added: $2 -> $PWD"
            ;;
        "")
            builtin cd ;;
        *)
            # 1. If it's a real directory, a relative path (like ..), or a flag like '-'
            if [ -d "$1" ] || [ "$1" = "-" ]; then
                builtin cd "$@"
            else
                # 2. Otherwise, check if it matches a saved shortcut
                local target=$(grep "^$1=" "$SHORTCUTS_FILE" | cut -d'=' -f2-)
                if [ -n "$target" ]; then
                    builtin cd "$target"
                else
                    # 3. Fallback to standard cd (to show proper error message)
                    builtin cd "$@"
                fi
            fi
            ;;
    esac
}

# Zsh Autocomplete function
_cd_shortcuts_completion() {
    local -a shortcuts
    shortcuts=(-h --help -add)
    
    # Dynamically pull keywords from the text file for autocomplete
    if [ -f "$HOME/.cd_shortcuts.txt" ]; then
        while IFS='=' read -r key val; do
            shortcuts+=("$key")
        done < "$HOME/.cd_shortcuts.txt"
    fi
    
    _describe 'shortcuts' shortcuts
    _path_files -/
}

Activating the Custom Command in Zsh

To hook your new script into your shell session and override the default cd command, add the following snippet to your ~/.zshrc file:

# Load the shortcuts script and override cd
source ~/scripts/cd_shortcuts.sh
cd() { _custom_cd_logic "$@"; }
compdef _cd_shortcuts_completion cd

Once saved, reload your terminal configuration using:

source ~/.zshrc

Adapting the Setup for Bash

While the core directory navigation logic (`_custom_cd_logic`) works identically in Bash, the auto-completion mechanism needs to be adapted. Bash uses `compgen` and `COMPREPLY` instead of Zsh's `_describe`, and registers completions via the `complete` builtin rather than `compdef`.

1. The Bash Autocomplete Function Adjustment

Replace the Zsh autocomplete block inside your script with the following Bash-compatible version:

# Bash Autocomplete function
_cd_shortcuts_completion() {
    local cur shortcuts
    cur="${COMP_WORDS[COMP_CWORD]}"
    
    # Base options
    shortcuts="-h --help -add"
    
    # Dynamically pull keywords from the text file for autocomplete
    if [ -f "$HOME/.cd_shortcuts.txt" ]; then
        while IFS='=' read -r key val; do
            shortcuts="$shortcuts $key"
        done < "$HOME/.cd_shortcuts.txt"
    fi
    
    # Generate completions matching what the user has typed so far
    COMPREPLY=( $(compgen -W "$shortcuts" -- "$cur") )
}

2. Activating in Bash (`~/.bashrc`)

To register the override and completion hook inside a Bash environment, add this snippet to your `~/.bashrc` file instead:

# Load the shortcuts script, override cd, and set up Bash completion
source ~/scripts/cd_shortcuts.sh
cd() { _custom_cd_logic "$@"; }
complete -F _cd_shortcuts_completion cd

After saving, reload your Bash session using:

source ~/.bashrc

Key Benefits

• Familiarity: Standard operations like cd .. and cd - work out of the box.
• Speed: Quickly save deep paths using cd -add keyword and jump to them instantly with cd keyword.
• Smart Autocomplete: Pressing Tab after typing cd will present both custom shortcuts and native system paths.