Arreglar un Claude Code lento o atascado

Esta página es para cuando Claude Code ya está en marcha pero va mal: mucha CPU o memoria, un cuelgue, una compactación que no acaba, caracteres raros, un portapapeles que queda vacío o búsquedas que no encuentran nada. Empieza por la comprobación rápida y salta a tu síntoma.

Empieza por la revisión

Ejecuta /doctor dentro de Claude Code. Revisa tu instalación, tus ajustes, las extensiones y el uso de contexto, y propone arreglos que puede aplicar cuando confirmes. Si claude no arranca, ejecuta claude doctor desde tu shell. /mcp muestra el estado de tus servidores MCP. Para errores de instalación o de inicio de sesión, o ajustes y hooks que no se aplican, la documentación oficial tiene páginas aparte; nuestra guía de depuración cubre la parte de ajustes.

Mucha CPU o memoria

1. Ejecuta /compact con regularidad. Si responde Not enough messages to compact, la conversación tiene muy pocos turnos para resumir, algo que puede pasar aunque el contexto esté lleno si un solo pegado enorme lo llenó.
2. Cierra y reinicia Claude Code entre tareas grandes.
3. Añade a tu .gitignore los directorios grandes de compilación.
4. Reinicia con claude --safe-mode. Apaga todas las personalizaciones en esa sesión; si el uso baja, la causa es un plugin, un servidor MCP o un hook, y la guía de depuración explica cómo saber cuál.

Si la memoria de una sesión pasa de 2,5 GB, aparece un aviso crítico de memoria. Reinicia Claude Code y ejecuta claude --continue para retomar la conversación en un proceso nuevo. Si la memoria sigue alta, /heapdump (escríbelo entero; está oculto en el menú de comandos) escribe dos archivos en tu Escritorio: una instantánea de memoria y un -diagnostics.json.

Ojo: la instantánea contiene todas las cadenas del proceso, incluida toda tu conversación y las credenciales que haya en ella. No la adjuntes nunca a una incidencia pública ni la compartas. La documentación dice que, para informar de un problema, adjuntes solo el archivo de diagnóstico.

La compactación falla: «Autocompact is thrashing»

Significa que la compactación funcionó pero un archivo o una salida de herramienta volvió a llenar el contexto enseguida, varias veces seguidas, así que Claude Code dejó de reintentar. Para recuperarte:

1. Pide a Claude que lea el archivo grande por trozos, como un rango de líneas o una función, y no entero.
2. Ejecuta /compact con un enfoque que descarte la salida grande, por ejemplo /compact keep only the plan and the diff.
3. Pasa el trabajo con archivos grandes a un subagente, que tiene su propia ventana de contexto.
4. Ejecuta /clear si no necesitas la conversación anterior.

Si vuelve después de /clear, ejecuta /context y compara la fila Messages con el resto. Si Messages es la mayor, un archivo o una salida está rellenando la ventana: repite los pasos de arriba. Si las demás filas juntas son mayores, lo que se carga al empezar deja poco sitio; mira la ventana de contexto y gastar menos cuota.

Se cuelga

Pulsa Ctrl+C para cancelar la operación en curso. Si nada responde, cierra la terminal y reinicia. No pierdes la conversación: ejecuta claude --resume en el mismo directorio para retomar la sesión.

Problemas de pantalla

• Cuadros, manchas o glifos equivocados en la terminal integrada de VS Code, Cursor y editores parecidos: lo más probable es el renderizado por GPU de la terminal. Ejecuta /terminal-setup para poner terminal.integrated.gpuAcceleration del editor en "off", o ponlo a mano y recarga la ventana.
• Un >0q suelto al arrancar o un >4m al salir: vienen de terminales construidas sobre una biblioteca VTE antigua. La documentación dice que actualices Claude Code; una versión más nueva omite esas secuencias en esas terminales.
• La rueda del ratón va muy lenta en el modo de pantalla completa: ejecuta /scroll-speed para subir las líneas por muesca, o pulsa PgUp y PgDn para media pantalla. /tui default vuelve al renderizador clásico y al historial de tu propia terminal.
• Una tabla larga sale cortada: solo se limita lo que se ve, a 200 filas. La tabla completa sigue en la conversación y /copy copia todas las filas. Si es enorme, pide a Claude que la escriba en un archivo.

El portapapeles queda vacío

• Con el sandbox activado, herramientas como pbcopy, xclip y wl-copy pueden fallar al llegar a tu portapapeles desde un comando dentro del sandbox. Pide a Claude que imprima el contenido en su respuesta y ejecuta /copy, que escribe en el portapapeles desde el propio Claude Code.
• Por SSH, Claude Code no puede ejecutar una herramienta de portapapeles en tu equipo local. Fuera de tmux, envía el texto a tu terminal como una secuencia de escape OSC 52 y tu terminal decide si la usa. Algunas la ignoran: iTerm2 necesita activar un ajuste y el Terminal.app de macOS no la admite. /copy dice «Copied to clipboard» aunque el texto no haya llegado. Puedes mantener pulsada la tecla de selección nativa de tu terminal mientras arrastras, o poner CLAUDE_CODE_DISABLE_MOUSE=1 en la máquina remota.

Las búsquedas no encuentran nada

Si la herramienta de búsqueda, las menciones @archivo, los agentes o las skills propias no encuentran archivos, puede que el ripgrep incluido no funcione en tu sistema. Instala el paquete de tu plataforma (por ejemplo brew install ripgrep en macOS, sudo apt install ripgrep en Ubuntu o Debian, winget install BurntSushi.ripgrep.MSVC en Windows) y pon USE_BUILTIN_RIPGREP a 0, en tu shell o en el bloque env de tu settings.json:

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

Ejecuta claude doctor y comprueba que la línea Search muestra la ruta de tu ripgrep del sistema y no OK (bundled). Mira qué archivo de ajustes manda si dudas de dónde ponerlo.

La búsqueda en WSL devuelve poco

Leer archivos entre los sistemas de archivos de Windows y Linux es lento en WSL, y eso puede dar menos coincidencias de las esperadas. claude doctor sigue mostrando Search como correcto. La documentación sugiere hacer búsquedas más concretas (nombra un directorio o un tipo de archivo), tener el proyecto en el sistema de archivos de Linux (/home/) y no en /mnt/c/, o ejecutar Claude Code de forma nativa en Windows.

Sigues atascado

Ejecuta /doctor y /mcp, usa /feedback dentro de Claude Code para informar de un problema a Anthropic, o mira las incidencias del proyecto en GitHub. Para problemas de cuenta, facturación o suscripción, contacta con el soporte de Anthropic.

Esta página sigue la documentación de problemas de Anthropic tal como la leemos en octubre de 2026. No tenemos relación con Anthropic. La escribimos a partir de la documentación y no hemos probado todos los casos. Los comandos, los límites y los arreglos cambian entre versiones, y donde esta página y la documentación no coincidan, manda la documentación. Todas las guías están en el índice de guías.

Mira también: Arreglar «command not found: claude» · Modo pantalla completa: parpadeo y scroll.

La skill gratis loop-stop da a las tareas largas un límite y una regla de parada, que además evita que las sesiones crezcan hasta atragantarse. Si quieres una segunda mirada a tu CLAUDE.md y a tus ajustes, el Tune-Up Kit es una lista de comprobación para eso (la ficha está en inglés).