Cuando la CLI de Claude Code ocupa el 100% de la CPU — Causas y Soluciones
Hallazgo
Mientras trabajaba el día anterior, Claude Code se congeló repentinamente y tuve que forzar su cierre. A la mañana siguiente, mi MacBook estaba más caliente de lo habitual. Al abrir el Monitor de Actividad (Activity Monitor), vi que el proceso Claude Code v2.1.27 estaba ocupando el 100% de la CPU.
Ruta: ~/.local/share/claude/versions/2.1.27
Comando: claude --continue
CPU: 99.5%
Memoria: ~600MB
Tiempo de ejecución: Aprox. 8 horasUn proceso de servidor de desarrollo ejecutado anteriormente por Claude Code como una Habilidad (Skill) no se había cerrado y permanecía como un zombi consumiendo la CPU.
Intenté con pkill claude, pero no murió, así que tuve que forzar el cierre con kill -9 <PID>.
Finalmente, lo solucioné limpiando los archivos de sesión y haciendo un downgrade a una versión estable con claude install 2.1.22. Desde entonces, no ha vuelto a ocurrir el problema de uso de CPU.
Causa
Este es un bug conocido en la CLI de Claude Code v2.1.27. Hay múltiples incidencias registradas en GitHub con los mismos síntomas.
1. Archivos de sesión inflados (Lo más probable)
Cuando los archivos de sesión .jsonl que se acumulan bajo ~/.claude/projects/ crecen demasiado, el análisis (parsing) entra en un bucle infinito de CPU.
claude --continue carga el archivo de sesión anterior, por lo que se ve directamente afectado por este problema.
- Funcionamiento normal en v2.1.25, reproducción confirmada en v2.1.27.
- Se soluciona inmediatamente al eliminar el archivo de sesión.
Referencia: #22041 — CLI hangs at 99% CPU on startup with large session .jsonl files
2. Hooks + Conflicto de instancias paralelas
Desde la v2.1.23, si se ejecutan múltiples instancias de Claude Code con los hooks activados, se produce un bloqueo (hang) del 100% de la CPU.
Referencia: #22172 — v2.1.23+ causes 100% CPU hang with multiple parallel instances and hooks
3. Espera activa (busy-wait) en estado inactivo
Las llamadas a setImmediate() se programan repetidamente sin ceder el control (yield), ocupando la CPU incluso cuando no se realiza ninguna tarea.
Referencia: #17148 — Claude Code consumes 100%+ CPU when idle in terminal
Solución
Paso 1: Encontrar el proceso zombi
ps aux | grep claude | grep -v grepVerifica los procesos relacionados con claude y sus PID en la salida.
Paso 2: Finalizar el proceso
pkill claude no funciona con este proceso zombi. Debes especificar el PID directamente para finalizarlo.
# pkill no funciona
pkill claude # ← Sin respuesta
# Forzar cierre especificando el PID directamente
kill -9 <PID>Paso 3: Limpiar archivos de sesión inflados
# Verificar tamaño de archivos de sesión
du -sh ~/.claude/projects/*/
# Eliminar el archivo de sesión problemático
rm ~/.claude/projects/<ruta-del-proyecto>/*.jsonlSi eliminas el archivo de sesión, no podrás continuar la conversación anterior con claude --continue. Haz una copia de seguridad si es necesario antes de borrar.
Paso 4: Downgrade de versión (usuarios de hooks)
Si estás usando hooks, haz un downgrade a la versión estable anterior.
Puedes instalar una versión específica usando el comando claude install.
# Downgrade a una versión específica (sin el prefijo v)
claude install 2.1.22
# Verificar
claude --versionAtención: Si ejecutas
claude install stableoclaude update, volverás a la última versión estable.
Prevención
Si usas v2.1.23 o superior:
| Método | Descripción |
|---|---|
| Limpieza periódica de sesiones | Limpiar archivos .jsonl bajo ~/.claude/projects/ si superan los 10MB |
| Hábito de verificar el cierre | Después de cerrar claude, verificar con ps aux | grep claude si el proceso realmente murió |
Evitar el abuso de --continue |
Cuanto más larga la sesión, más se infla el .jsonl. Es más seguro empezar con una nueva sesión |
| Cuidado con hooks + ejecución paralela | No ejecutar múltiples instancias simultáneamente con hooks activados |
| Seguimiento de actualizaciones | Verificar correcciones relacionadas en anthropics/claude-code Issues |
/clearsolo inicializa el contexto de la conversación, pero no elimina el archivo.jsonlen sí. No tiene un efecto directo en la prevención de la inflación del archivo de sesión.
Colección de problemas relacionados
- #22041 — CLI hangs at 99% CPU on startup with large session .jsonl files
- #22172 — v2.1.23+ causes 100% CPU hang with parallel instances and hooks
- #17148 — Claude Code consumes 100%+ CPU when idle in terminal
- #11122 — Multiple Claude CLI processes accumulate causing high CPU usage
- #11377 — Memory leak: 23GB RAM and 143% CPU after 14 hours
Pedir directamente a la IA
Copia y pega los siguientes prompts en tu IA (Claude, ChatGPT, etc.) según tu situación, y ella misma diagnosticará y organizará todo.
Cuando Claude Code se congela y solo cierras la terminal
Estaba usando Claude Code y se congeló, así que forcé el cierre de la terminal.
Puede haber quedado un proceso zombi en segundo plano, por favor verifícalo y límpialo.
1. Verifica procesos restantes con `ps aux | grep claude | grep -v grep`
2. Si se encuentra, fuerza el cierre con `kill -9 <PID>` (pkill no funciona)
3. Verifica archivos de sesión inflados con `du -sh ~/.claude/projects/*/` → Elimina .jsonl que superen 10MB
Muestra el resultado de la ejecución en cada paso y explica qué hiciste.Cuando el MacBook está más caliente de lo habitual
El MacBook está más caliente de lo habitual. Un proceso zombi de Claude Code podría estar ocupando la CPU.
Diagnostícalo y soluciónalo.
1. Verifica procesos zombi con `ps aux | grep claude | grep -v grep`
2. Si se encuentra, fuerza el cierre con `kill -9 <PID>` (pkill no funciona)
3. Verifica archivos de sesión inflados con `du -sh ~/.claude/projects/*/` → Elimina .jsonl que superen 10MB
4. Si usas hooks, considera hacer downgrade a la versión estable con `claude install 2.1.22`
Muestra el resultado de la ejecución en cada paso y explica qué hiciste.Actualmente he hecho downgrade a claude install 2.1.22. Actualizaré cuando salga una versión con este problema corregido.