Cómo Activar el Autocompletado de Comandos en ZSH

ZSH tiene un sistema de autocompletado potente, pero no lo hace todo de fábrica. Necesitas activar el autocompletado con Tab integrado y, opcionalmente, añadir plugins para obtener sugerencias en línea. Esta guía cubre las tres capas: el sistema de autocompletado nativo de ZSH, el plugin zsh-autosuggestions y el plugin zsh-autocomplete.

ZSH viene preinstalado en macOS (desde Catalina). En Linux, tendrás que instalarlo primero.

Guías relacionadas de ZSH:

• Cómo Activar el Resaltado de Sintaxis en Zsh
• Los 15 Mejores Plugins de Oh My ZSH que Debes Probar
• Zoxide: La Forma Más Inteligente de Navegar por tu Terminal

Autocompletado de ZSH vs autosugerencias

Estos términos se confunden constantemente. Esto es lo que hace realmente cada uno:

Autocompletado integrado (compinit) — El sistema de autocompletado nativo de ZSH. Cuando pulsas Tab, muestra los posibles completados para comandos, opciones, nombres de archivo, variables y más. Es sensible al contexto: sabe que git ch<Tab> debe mostrar checkout y cherry-pick, no archivos aleatorios. Es la base: todo lo demás se construye sobre él.

zsh-autosuggestions — Un plugin que muestra una sugerencia atenuada mientras escribes, basada en tu historial de comandos. Piensa en ello como las sugerencias en línea de fish shell portadas a ZSH. Escribes dock y te sugiere docker ps desde tu historial en texto tenue. Pulsa → para aceptar la sugerencia. Es el plugin de autocompletado para ZSH más popular, con más de 35.000 estrellas en GitHub.

zsh-autocomplete — Un plugin diferente (de Marlon Richert) que muestra un menú desplegable de completados en tiempo real mientras escribes, sin pulsar Tab. Más parecido al autocompletado de un IDE. Escribes git y aparece inmediatamente una lista de subcomandos debajo del prompt. Menos estrellas (~6.600), pero un enfoque de UX distinto.

La mayoría de la gente quiere el autocompletado integrado + zsh-autosuggestions. Esa es la configuración estándar.

Paso 1: Activa el sistema de autocompletado integrado de ZSH

El sistema de autocompletado de ZSH (compinit) necesita ser inicializado. Si usas Oh My Zsh, esto ya está hecho por ti. Si ejecutas ZSH sin más, añade esto a tu ~/.zshrc:

autoload -Uz compinit && compinit

Esto carga el sistema de autocompletado y lo inicializa. Sin esta línea, el autocompletado básico con Tab no funcionará correctamente: solo obtendrás completado de nombres de archivo, no completados de comandos sensibles al contexto.

Para acelerar compinit (puede ser lento porque comprueba muchos archivos al arrancar), puedes cachear el archivo de volcado:

# Reconstruye el archivo de volcado solo una vez al día
autoload -Uz compinit
if [[ -n ${ZDOTDIR:-$HOME}/.zcompdump(#qN.mh+24) ]]; then
  compinit
else
  compinit -C
fi

La opción -C omite la comprobación de seguridad y usa el archivo de volcado cacheado. El condicional lo reconstruye solo si el volcado tiene más de 24 horas.

Estilos de autocompletado útiles

Añade esto a tu ~/.zshrc después de compinit para mejorar el comportamiento de autocompletado por defecto:

# Autocompletado sin distinguir mayúsculas y minúsculas
zstyle ':completion:*' matcher-list 'm:{a-zA-Z}={A-Za-z}'

# Selección por menú: usa las flechas para navegar por los completados
zstyle ':completion:*' menu select

# Agrupa los completados por tipo (comandos, archivos, opciones)
zstyle ':completion:*' group-name ''

# Muestra descripciones para los completados
zstyle ':completion:*' format '%F{yellow}-- %d --%f'

# Colorea el completado de archivos
zstyle ':completion:*' list-colors "${(s.:.)LS_COLORS}"

Con menu select, Tab muestra los completados en un menú navegable. Las flechas se mueven por él y Enter selecciona.

Paso 2: Instala zsh-autosuggestions

Este plugin te da sugerencias en línea estilo fish basadas en tu historial. Hay dos formas de instalarlo.

Opción A: Con Oh My Zsh

Si ya usas Oh My Zsh:

# Clona el plugin en el directorio de plugins personalizados de Oh My Zsh
git clone https://github.com/zsh-users/zsh-autosuggestions \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions

Luego edita ~/.zshrc y añade zsh-autosuggestions a tu lista de plugins:

plugins=(git zsh-autosuggestions)

Si aún no tienes Oh My Zsh instalado:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

Opción B: Instalación manual (sin Oh My Zsh)

git clone https://github.com/zsh-users/zsh-autosuggestions ~/.zsh/zsh-autosuggestions

Añade esto a tu ~/.zshrc:

source ~/.zsh/zsh-autosuggestions/zsh-autosuggestions.zsh

Opción C: Con Homebrew (macOS)

brew install zsh-autosuggestions

Añade a ~/.zshrc:

source $(brew --prefix)/share/zsh-autosuggestions/zsh-autosuggestions.zsh

Recarga tu shell

source ~/.zshrc

O simplemente abre una nueva pestaña de terminal.

Paso 3: Pruébalo

Empieza a escribir un comando que hayas usado antes. Deberías ver aparecer una sugerencia atenuada después del cursor. Por ejemplo, escribe ec y podría sugerirte echo "hello" desde tu historial.

Atajos de teclado para zsh-autosuggestions:

También puedes aceptar con Ctrl+E (fin de línea) si tus atajos de teclado lo permiten.

Personalizar zsh-autosuggestions

Añade esto a ~/.zshrc después de la línea source (o en $ZSH_CUSTOM si usas Oh My Zsh).

Cambiar el color de las sugerencias

El valor por defecto es fg=8 (gris oscuro). Ajústalo si cuesta leerlo en tu terminal:

ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE="fg=240"

O usa un color hexadecimal:

ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE="fg=#666666"

Cambiar la estrategia de sugerencias

Por defecto, las sugerencias vienen de tu historial de comandos. También puedes usar los resultados del autocompletado con Tab o una combinación:

# Prueba primero el historial, con el sistema de autocompletado como respaldo
ZSH_AUTOSUGGEST_STRATEGY=(history completion)

# Usa solo el historial (por defecto, lo más rápido)
ZSH_AUTOSUGGEST_STRATEGY=(history)

# Como el historial, pero prioriza coincidencias posteriores al mismo comando previo
ZSH_AUTOSUGGEST_STRATEGY=(match_prev_cmd)

Usar (history completion) es más lento porque ejecuta el motor de autocompletado con cada pulsación de tecla. Quédate con (history) salvo que quieras completados de comandos que nunca has ejecutado.

Desactivar sugerencias en bloques pegados grandes

Cuando pegas un bloque grande de texto, las autosugerencias pueden ir lentas. Establece un límite de tamaño de buffer:

ZSH_AUTOSUGGEST_BUFFER_MAX_SIZE=20

Las sugerencias se desactivan para cualquier entrada de más de 20 caracteres.

Asignar Ctrl+Space para aceptar sugerencias

bindkey '^ ' autosuggest-accept

Opcional: Instala zsh-autocomplete para menús en tiempo real

Si quieres completados estilo IDE que aparecen mientras escribes (sin pulsar Tab), instala zsh-autocomplete en lugar de zsh-autosuggestions o junto a él:

git clone --depth 1 -- https://github.com/marlonrichert/zsh-autocomplete.git \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autocomplete

Añádelo a tu lista de plugins en ~/.zshrc:

plugins=(git zsh-autosuggestions zsh-autocomplete)

O sin Oh My Zsh:

git clone --depth 1 -- https://github.com/marlonrichert/zsh-autocomplete.git ~/.zsh/zsh-autocomplete

source ~/.zsh/zsh-autocomplete/zsh-autocomplete.plugin.zsh

Nota: Elimina cualquier llamada a compinit de tu .zshrc: zsh-autocomplete gestiona la inicialización por sí mismo.

Advertencia importante: zsh-autocomplete y zsh-autosuggestions hacen cosas diferentes y pueden entrar en conflicto visualmente. Muchos usuarios usan ambos, pero si la interfaz te parece recargada, quédate con uno. zsh-autosuggestions es más popular y ligero. zsh-autocomplete es más pesado pero muestra más completados.

Juntándolo todo

Aquí tienes un ~/.zshrc mínimo con todo lo esencial:

# Instalación de Oh My Zsh (si lo usas)
export ZSH="$HOME/.oh-my-zsh"
plugins=(git zsh-autosuggestions zsh-syntax-highlighting)
source $ZSH/oh-my-zsh.sh

# Estilos de autocompletado
zstyle ':completion:*' matcher-list 'm:{a-zA-Z}={A-Za-z}'
zstyle ':completion:*' menu select

# Configuración de autosugerencias
ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE="fg=240"
ZSH_AUTOSUGGEST_STRATEGY=(history)
ZSH_AUTOSUGGEST_BUFFER_MAX_SIZE=20

Sin Oh My Zsh:

# Sistema de autocompletado
autoload -Uz compinit
if [[ -n ${ZDOTDIR:-$HOME}/.zcompdump(#qN.mh+24) ]]; then
  compinit
else
  compinit -C
fi

# Estilos de autocompletado
zstyle ':completion:*' matcher-list 'm:{a-zA-Z}={A-Za-z}'
zstyle ':completion:*' menu select

# Plugins
source ~/.zsh/zsh-autosuggestions/zsh-autosuggestions.zsh
source ~/.zsh/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh

# Configuración de autosugerencias
ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE="fg=240"
ZSH_AUTOSUGGEST_STRATEGY=(history)

El plugin zsh-syntax-highlighting también vale la pena: colorea los comandos mientras escribes, así que puedes detectar erratas antes de pulsar Enter.

Solución de problemas

Las sugerencias no aparecen: Asegúrate de que compinit está cargado. Compruébalo con which _complete: si no devuelve nada, el sistema de autocompletado no está inicializado.

Texto gris invisible en iTerm2: Ve a iTerm2 Settings → Profiles → Colors. Asegúrate de que “Bright Black” (color ANSI 8) es diferente del color de fondo. A veces son iguales, lo que hace invisibles las sugerencias.

Arranque lento del shell: Si compinit tarda demasiado, usa la versión cacheada mostrada en el Paso 1. Comprueba también si estás cargando demasiados plugins: cada uno añade tiempo de arranque.

Los completados no funcionan tras instalar una nueva herramienta CLI: Algunas herramientas (como kubectl, docker, gh) requieren que generes y cargues sus scripts de autocompletado. Por ejemplo:

# kubectl
kubectl completion zsh > ~/.zsh/completions/_kubectl

# docker
docker completion zsh > ~/.zsh/completions/_docker

# GitHub CLI
gh completion -s zsh > ~/.zsh/completions/_gh

Asegúrate de que ~/.zsh/completions está en tu fpath antes de compinit:

fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit && compinit

¿Quieres una alternativa con todo incluido? Fish Shell trae de serie autosugerencias, resaltado de sintaxis y completados ricos. Sin necesidad de plugins. Mira la comparación Fish Shell vs Zsh si quieres explorar esa opción.

¿Qué configuración deberías usar?

Para la mayoría: Oh My Zsh (o ZSH sin más) + zsh-autosuggestions + zsh-syntax-highlighting es el punto óptimo. Es rápido, probado y cubre el 90% de lo que necesitas.