zsh-alias-highlight

A Zsh plugin that highlights aliases while you type and provides visual feedback when executing them.

Features

i asked claude to write this section. plugin is self-explanatory anyways.

• Typing-time highlighting: Aliases highlighted in magenta as you type (requires zsh-syntax-highlighting)
• Execution-time feedback: Multiple display modes to show what alias actually ran
• Bypass detection: Supports standard Zsh bypass methods (\, command, nocorrect)
• Multiple display modes: Choose how aliases are shown after execution
• Theme-friendly: Uses Zsh color codes, works with any prompt

Requirements

• Zsh 5.0 or later
• zsh-syntax-highlighting

Installation

Manual

git clone https://github.com/cyberistic/zsh-alias-highlight ~/.zsh/zsh-alias-highlight

Add to ~/.zshrc:

source ~/.zsh/zsh-alias-highlight/zsh-alias-highlight.plugin.zsh

Usage

Display Modes

The plugin supports multiple display modes controlled by ZSH_ALIAS_HIGHLIGHT_MODE:

persist (default)

Keeps the magenta typing highlight, no execution annotation. Clean and minimal.

# You type: ls
# While typing: ls appears in magenta
# After execution: no additional annotation

none

No execution annotation, but typing highlight still works.

# Same as persist

subset

Highlights matching characters in cyan, non-matching in magenta.

# You type: cat file.txt
# Alias expands to: bat
# Shows: cat (c, a, t in cyan where they match 'bat')

prefix

Shows full alias expansion in brackets.

# You type: ls
# Alias expands to: eza --icons --group-directories-first
# Shows: [eza --icons --group-directories-first]ls

prefix-truncated

Shows alias expansion truncated to 10 characters.

# You type: ls
# Alias expands to: eza --icons --group-directories-first
# Shows: [eza --icon..]ls

prefix-first-word

Shows only the first word of the alias expansion.

# You type: ls
# Alias expands to: eza --icons --group-directories-first
# Shows: [eza]ls (with 'ls' in magenta)

off

Completely disabled - no highlighting or annotation. Falls back to default zsh-syntax-highlighting behavior.

Bypassing Aliases

Use standard Zsh methods to bypass alias expansion:

\cat file.txt          # backslash prefix
command cat file.txt   # command builtin
nocorrect cat file.txt # nocorrect builtin

When you bypass an alias, the plugin won't show any annotation.

Configuration

Add these to your ~/.zshrc before loading the plugin:

# Display mode (default: persist)
export ZSH_ALIAS_HIGHLIGHT_MODE=persist  # none | subset | prefix | prefix-truncated | prefix-first-word | persist | off

# Color for alias highlighting while typing (default: magenta)
export ZSH_ALIAS_HIGHLIGHT_COLOR=magenta  # any color name or 256-color code

# Color for matching characters in subset mode (default: cyan)
export ZSH_ALIAS_DIFF_COLOR=cyan

# Color for prefix brackets (default: cyan)
export ZSH_ALIAS_PREFIX_COLOR=cyan

# Optional: Override prompt auto-detection (if needed)
export ZSH_ALIAS_HIGHLIGHT_PROMPT='%F{cyan}❯%f '

Prompt Handling

The plugin automatically detects your prompt by reading the PS1 variable. In most cases, this works perfectly without any configuration.

Only set ZSH_ALIAS_HIGHLIGHT_PROMPT if:

• Your prompt doesn't reprint correctly
• You want a simpler prompt for the reprinted line
• You're using a complex prompt framework (like oh-my-posh, starship) that doesn't work with auto-detection

# Examples of manual prompt override:
export ZSH_ALIAS_HIGHLIGHT_PROMPT='%F{cyan}❯%f '    # Cyan arrow
export ZSH_ALIAS_HIGHLIGHT_PROMPT='%F{green}→%f '  # Green arrow
export ZSH_ALIAS_HIGHLIGHT_PROMPT='$ '             # Simple dollar sign

Multi-word Aliases

alias ls='eza --icons --group-directories-first'

# prefix-first-word mode shows: [eza]ls
# prefix-truncated mode shows: [eza --icon..]ls
# prefix mode shows: [eza --icons --group-directories-first]ls

Bypassing Aliases

alias ls='eza'

ls        # runs eza (with plugin annotation)
\ls       # runs /bin/ls (no annotation)
command ls # runs /bin/ls (no annotation)

Troubleshooting

Typing-time highlighting not working

Make sure zsh-syntax-highlighting is:

1. Installed
2. Loaded before this plugin
3. Actually active in your shell

Test it:

# Should show magenta if working
echo ${ZSH_HIGHLIGHT_STYLES[alias]}

Colors not showing

Test if your terminal supports colors:

print -P "%F{magenta}test magenta%f"
print -P "%F{cyan}test cyan%f"

Prompt looks wrong after execution

The plugin auto-detects your prompt from PS1 or PROMPT variables. If it doesn't work correctly:

# Set a simple version of your prompt
export ZSH_ALIAS_HIGHLIGHT_PROMPT='❯ '

For complex prompt frameworks (powerlevel10k, starship with transient):

# Option 1: Use persist mode (no reprinting)
export ZSH_ALIAS_HIGHLIGHT_MODE=persist

# Option 2: Set a simple prompt for reprinting
export ZSH_ALIAS_HIGHLIGHT_PROMPT='> '

Testing your prompt setup:

# Check what the plugin captured
echo "Captured: $_ALIAS_HIGHLIGHT_LAST_PROMPT"

# Test if your mode requires reprinting
echo "Mode: $ZSH_ALIAS_HIGHLIGHT_MODE"

Contributions

Contributions are welcome! Please open issues or pull requests. :)

License

MIT License - see LICENSE file for details