Cómo Optimizar Claude CLI: De 100% CPU a Sistema Vigilado 24/7

El Problema: Claude CLI Consumiendo Todos los Recursos

Trabajando con Claude CLI como herramienta principal de desarrollo, nos enfrentamos a un desafío crítico: el proceso consumía más del 100% de CPU de manera constante durante toda la jornada laboral. Este tipo de problemas no solo afectan el rendimiento del sistema, sino que pueden generar costos innecesarios en servidores en la nube y degradar la experiencia de desarrollo.

La investigación reveló múltiples vectores de sobrecarga que, al combinarse, creaban un cuello de botella significativo en el sistema.

Anatomía del Problema: Los Números Reales

El diagnóstico inicial reveló hallazgos contundentes:

Acumulación de archivos de debug:

• 432 archivos ocupando 73MB de espacio
• Generación constante de I/O que mantenía el disco trabajando
• 88 shell-snapshots acumulados sin rotación automática

Sobrecarga de configuración:

• 379 reglas de permisos individuales procesadas en cada inicio
• 13 agentes con frontmatter YAML malformado generando errores de parsing
• Sesiones de 4 horas acumulando 32 errores 401 sin timeout

Uso excesivo de API:

• 1,271 llamadas a API en una sola sesión
• Reintentos automáticos sin backoff exponencial
• Sin límites de rate-limiting configurados

Estos números no son teóricos: son métricas reales extraídas de un entorno de producción.

La Solución: Tres Capas de Optimización

1. Limpieza Agresiva de Archivos

El primer paso fue eliminar la acumulación innecesaria:

Reducción de archivos de debug
Antes: 73MB en 432 archivos
Después: 9.9MB en 61 archivos
Reducción: 86%
Limpieza de snapshots
Antes: 356KB en 88 archivos
Después: 20KB en archivos recientes
Reducción: 94%

Esta limpieza no solo liberó espacio: redujo drásticamente las operaciones de I/O que contribuían al uso elevado de CPU.

2. Optimización de Permisos con Wildcards

Las 379 reglas de permisos individuales se consolidaron en solo 4 reglas utilizando wildcards:

{
"directoryWhitelist": [
"/home/irvinux/MasterProject/**",
"/tmp/**",
"/var/log/claude_**",
"/home/irvinux/.claude/**"
]
}

Esta simplificación reduce el tiempo de parsing al inicio de cada sesión y elimina la necesidad de actualizar permisos constantemente.

3. Corrección de Agentes con Frontmatter YAML

Ocho agentes tenían frontmatter malformado que generaba errores de parsing en cada invocación:

• CriticAgent.md
• LeadsAgent.md
• BusinessCritic.md
• CodeCritic.md
• n8n-auditor.md
• CyberGirl.md
• ConstructionCalcAgent.md
• N8nWorkflowAgent.md

La corrección del frontmatter YAML eliminó errores repetitivos y mejoró la estabilidad del sistema.

Sistema de Monitoreo Automatizado

Health Monitor: Diagnóstico Manual y Automático

Se desarrolló un script de monitoreo que permite verificar la salud del sistema en cualquier momento:

Verificación manual
./scripts/claude_health_monitor.sh
Limpieza automática
./scripts/claude_health_monitor.sh --fix

El script verifica:

• Uso de CPU y memoria
• Tamaño de archivos de debug
• Número de shell-snapshots
• Duración de sesiones activas
• Tasa de errores en logs

Watchdog Service: Protección 24/7

Para prevenir futuras sobrecargas, se implementó un servicio systemd que monitorea el sistema cada 5 minutos:

Acciones automáticas:

• CPU > 90%: ejecuta limpieza de archivos temporales
• CPU > 150%: termina procesos antiguos de Claude CLI
• Memoria > 50%: limpia directorio /tmp
• Sesión > 4 horas: envía alerta a Telegram
• Más de 10 errores en 30 minutos: alerta crítica
• Debug > 100MB: limpieza automática

Comandos de gestión
sudo systemctl status claude-watchdog
tail -f /var/log/claude_watchdog.log
sudo systemctl restart claude-watchdog

Protección a Nivel de Kernel: cgroups v2

Como capa adicional de protección, se configuraron límites duros a nivel de kernel usando cgroups v2:

/etc/systemd/system/user-1000.slice.d/cpu-limit.conf
[Slice]
CPUQuota=360%      # 90% de 4 cores
MemoryMax=12G
MemorySwapMax=2G
TasksMax=512
IOWeight=50

Esta configuración garantiza que incluso si el watchdog falla, el kernel impedirá que un proceso consuma todos los recursos del sistema.

Verificación del límite:

cat /sys/fs/cgroup/user.slice/user-1000.slice/cpu.max
Output: 360000 100000 (360% = 90% de 4 cores)

Resultados Medibles

Antes de la optimización:

• CPU: 100%+ constante
• Archivos debug: 73MB
• Reglas de permisos: 379
• Errores acumulados: 32 en 4 horas

Después de la optimización:

• CPU: 36% (uso normal)
• Archivos debug: 9.9MB (-86%)
• Reglas de permisos: 4 (wildcards)
• Sistema de alertas: activo 24/7

Lecciones Aprendidas

1. Monitoreo proactivo es esencial

Esperar a que un sistema falle no es una estrategia. El watchdog detecta problemas antes de que se vuelvan críticos.

2. Los límites de kernel son la última línea de defensa

Los scripts pueden fallar, pero cgroups v2 garantiza protección a nivel de sistema operativo.

3. La simplificación mejora el rendimiento

Reducir 379 reglas a 4 wildcards no solo es más elegante: es significativamente más rápido de procesar.

Este enfoque de tres capas (limpieza + monitoreo + límites de kernel) crea un sistema robusto que mantiene Claude CLI funcionando de manera eficiente sin intervención manual constante.

---