everything-claude-code/docs/es/TROUBLESHOOTING.md

Guía de Resolución de Problemas

Problemas comunes y soluciones para el plugin Everything Claude Code (ECC).

Tabla de Contenidos

• Problemas de Memoria y Contexto
• Fallos del Harness de Agentes
• Errores de Hooks y Flujos de Trabajo
• Instalación y Configuración
• Problemas de Rendimiento
• Mensajes de Error Comunes
• Obtener Ayuda

---

Problemas de Memoria y Contexto

Desbordamiento de la Ventana de Contexto

Síntoma: Errores de "Context too long" o respuestas incompletas

Causas:

• Archivos grandes que superan los límites de tokens
• Historial de conversación acumulado
• Múltiples salidas grandes de herramientas en una sola sesión

Soluciones:

# 1. Borrar el historial de conversación y empezar de nuevo
# Usa Claude Code: "New Chat" o Cmd/Ctrl+Shift+N

# 2. Reducir el tamaño del archivo antes del análisis
head -n 100 large-file.log > sample.log

# 3. Usar streaming para salidas grandes
head -n 50 large-file.txt

# 4. Dividir las tareas en fragmentos más pequeños
# En lugar de: "Analiza los 50 archivos"
# Usa: "Analiza los archivos en el directorio src/components/"

Fallos en la Persistencia de Memoria

Síntoma: El agente no recuerda el contexto u observaciones previas

Causas:

• Hooks de continuous-learning deshabilitados
• Archivos de observaciones corruptos
• Fallos en la detección del proyecto

Soluciones:

# Verificar si las observaciones se están registrando
ls ~/.claude/homunculus/projects/*/observations.jsonl

# Encontrar el hash id del proyecto actual
python3 - <<'PY'
import json, os
registry_path = os.path.expanduser("~/.claude/homunculus/projects.json")
with open(registry_path) as f:
    registry = json.load(f)
for project_id, meta in registry.items():
    if meta.get("root") == os.getcwd():
        print(project_id)
        break
else:
    raise SystemExit("Hash del proyecto no encontrado en ~/.claude/homunculus/projects.json")
PY

# Ver observaciones recientes para ese proyecto
tail -20 ~/.claude/homunculus/projects/<hash-del-proyecto>/observations.jsonl

# Hacer copia de seguridad de un archivo de observaciones corrupto antes de recrearlo
mv ~/.claude/homunculus/projects/<hash-del-proyecto>/observations.jsonl \
  ~/.claude/homunculus/projects/<hash-del-proyecto>/observations.jsonl.bak.$(date +%Y%m%d-%H%M%S)

# Verificar que los hooks están habilitados
grep -r "observe" ~/.claude/settings.json

---

Fallos del Harness de Agentes

Agente No Encontrado

Síntoma: Errores de "Agent not loaded" o "Unknown agent"

Causas:

• Plugin no instalado correctamente
• Configuración incorrecta de la ruta del agente
• Incompatibilidad entre instalación por marketplace y manual

Soluciones:

# Verificar la instalación del plugin
ls ~/.claude/plugins/cache/

# Verificar que el agente existe (instalación por marketplace)
ls ~/.claude/plugins/cache/*/agents/

# Para instalación manual, los agentes deben estar en:
ls ~/.claude/agents/  # Solo agentes personalizados

# Recargar plugin
# Claude Code → Settings → Extensions → Reload

El Flujo de Trabajo se Cuelga

Síntoma: El agente empieza pero nunca termina

Causas:

• Bucles infinitos en la lógica del agente
• Bloqueado esperando entrada del usuario
• Timeout de red esperando la API

Soluciones:

# 1. Verificar procesos bloqueados
ps aux | grep claude

# 2. Habilitar modo debug
export CLAUDE_DEBUG=1

# 3. Establecer timeouts más cortos
export CLAUDE_TIMEOUT=30

# 4. Verificar conectividad de red
curl -I https://api.anthropic.com

Errores en el Uso de Herramientas

Síntoma: "Tool execution failed" o permiso denegado

Causas:

• Dependencias faltantes (npm, python, etc.)
• Permisos de archivo insuficientes
• Ruta no encontrada

Soluciones:

# Verificar que las herramientas requeridas están instaladas
which node python3 npm git

# Corregir permisos en los scripts de hook
chmod +x ~/.claude/plugins/cache/*/hooks/*.sh
chmod +x ~/.claude/plugins/cache/*/skills/*/hooks/*.sh

# Verificar que PATH incluye los binarios necesarios
echo $PATH

---

Errores de Hooks y Flujos de Trabajo

Los Hooks No Se Disparan

Síntoma: Los hooks pre/post no se ejecutan

Causas:

• Hooks no registrados en settings.json
• Sintaxis de hook inválida
• Script de hook no ejecutable

Soluciones:

# Verificar que los hooks están registrados
grep -A 10 '"hooks"' ~/.claude/settings.json

# Verificar que los archivos de hook existen y son ejecutables
ls -la ~/.claude/plugins/cache/*/hooks/

# Probar el hook manualmente
bash ~/.claude/plugins/cache/*/hooks/pre-bash.sh <<< '{"command":"echo test"}'

# Volver a registrar hooks (si se usa el plugin)
# Deshabilitar y volver a habilitar el plugin en la configuración de Claude Code

Incompatibilidad de Versiones de Python/Node

Síntoma: "python3 not found" o "node: command not found"

Causas:

• Instalación de Python/Node faltante
• PATH no configurado
• Versión incorrecta de Python (Windows)

Soluciones:

# Instalar Python 3 (si falta)
# macOS: brew install python3
# Ubuntu: sudo apt install python3
# Windows: Descargar de python.org

# Instalar Node.js (si falta)
# macOS: brew install node
# Ubuntu: sudo apt install nodejs npm
# Windows: Descargar de nodejs.org

# Verificar instalaciones
python3 --version
node --version
npm --version

# Windows: Asegurarse de que python (no python3) funciona
python --version

Falsos Positivos del Bloqueador del Servidor de Desarrollo

Síntoma: El hook bloquea comandos legítimos que mencionan "dev"

Causas:

• Contenido de heredoc disparando la coincidencia de patrón
• Comandos que no son de dev con "dev" en los argumentos

Soluciones:

# Esto está corregido en v1.8.0+ (PR #371)
# Actualiza el plugin a la última versión

# Solución alternativa: Envuelve los servidores de dev en tmux
tmux new-session -d -s dev "npm run dev"
tmux attach -t dev

# Deshabilitar temporalmente el hook si es necesario
# Edita ~/.claude/settings.json y elimina el hook pre-bash

---

Instalación y Configuración

El Plugin No Carga

Síntoma: Funcionalidades del plugin no disponibles después de la instalación

Causas:

• Caché del marketplace no actualizado
• Incompatibilidad de versión de Claude Code
• Archivos del plugin corruptos
• Configuración local de Claude eliminada o restablecida

Soluciones:

# Primero inspecciona qué sabe ECC sobre esta máquina
ecc list-installed
ecc doctor
ecc repair

# Solo reinstala si doctor/repair no puede restaurar los archivos faltantes

# Inspecciona la caché del plugin antes de cambiarla
ls -la ~/.claude/plugins/cache/

# Haz una copia de seguridad de la caché del plugin en lugar de eliminarla
mv ~/.claude/plugins/cache ~/.claude/plugins/cache.backup.$(date +%Y%m%d-%H%M%S)
mkdir -p ~/.claude/plugins/cache

# Reinstalar desde el marketplace
# Claude Code → Extensions → Everything Claude Code → Uninstall
# Luego reinstalar desde el marketplace

# Si el problema es el acceso al marketplace/cuenta, usa la recuperación de cuenta/facturación de ECC Tools por separado; no uses la reinstalación como sustituto de la recuperación de cuenta

# Verificar la versión de Claude Code
claude --version
# Requiere Claude Code 2.0+

# Instalación manual (si el marketplace falla)
git clone https://github.com/affaan-m/everything-claude-code.git
cp -r everything-claude-code ~/.claude/plugins/ecc

Falla la Detección del Gestor de Paquetes

Síntoma: Se usa el gestor de paquetes incorrecto (npm en lugar de pnpm)

Causas:

• No hay archivo de bloqueo presente
• CLAUDE_PACKAGE_MANAGER no está configurado
• Múltiples archivos de bloqueo confunden la detección

Soluciones:

# Configurar el gestor de paquetes preferido globalmente
export CLAUDE_PACKAGE_MANAGER=pnpm
# Añadir a ~/.bashrc o ~/.zshrc

# O configurar por proyecto
echo '{"packageManager": "pnpm"}' > .claude/package-manager.json

# O usar el campo de package.json
npm pkg set packageManager="pnpm@8.15.0"

# Advertencia: eliminar archivos de bloqueo puede cambiar las versiones de dependencias instaladas.
# Haz un commit o copia de seguridad del archivo de bloqueo primero, luego ejecuta una instalación limpia y vuelve a ejecutar CI.
# Solo hazlo cuando cambies intencionalmente de gestor de paquetes.
rm package-lock.json  # Si usas pnpm/yarn/bun

---

Problemas de Rendimiento

Tiempos de Respuesta Lentos

Síntoma: El agente tarda más de 30 segundos en responder

Causas:

• Archivos de observaciones grandes
• Demasiados hooks activos
• Latencia de red a la API

Soluciones:

# Archivar observaciones grandes en lugar de eliminarlas
archive_dir="$HOME/.claude/homunculus/archive/$(date +%Y%m%d)"
mkdir -p "$archive_dir"
find ~/.claude/homunculus/projects -name "observations.jsonl" -size +10M -exec sh -c '
  for file do
    base=$(basename "$(dirname "$file")")
    gzip -c "$file" > "'"$archive_dir"'/${base}-observations.jsonl.gz"
    : > "$file"
  done
' sh {} +

# Deshabilitar hooks no utilizados temporalmente
# Edita ~/.claude/settings.json

# Mantener pequeños los archivos de observaciones activos
# Los archivos de gran tamaño deben estar bajo ~/.claude/homunculus/archive/

Alto Uso de CPU

Síntoma: Claude Code consume 100% de CPU

Causas:

• Bucles de observación infinitos
• Observación de archivos en directorios grandes
• Fugas de memoria en hooks

Soluciones:

# Verificar procesos desbocados
top -o cpu | grep claude

# Deshabilitar el aprendizaje continuo temporalmente
touch ~/.claude/homunculus/disabled

# Reiniciar Claude Code
# Cmd/Ctrl+Q luego volver a abrir

# Verificar el tamaño del archivo de observaciones
du -sh ~/.claude/homunculus/*/

---

Mensajes de Error Comunes

"EACCES: permission denied"

# Corregir permisos de hooks
find ~/.claude/plugins -name "*.sh" -exec chmod +x {} \;

# Corregir permisos del directorio de observaciones
chmod -R u+rwX,go+rX ~/.claude/homunculus

"MODULE_NOT_FOUND"

# Instalar dependencias del plugin
cd ~/.claude/plugins/cache/ecc
npm install

# O para instalación manual
cd ~/.claude/plugins/ecc
npm install

"spawn UNKNOWN"

# Específico de Windows: Asegúrate de que los scripts usen los finales de línea correctos
# Convertir CRLF a LF
find ~/.claude/plugins -name "*.sh" -exec dos2unix {} \;

# O instalar dos2unix
# macOS: brew install dos2unix
# Ubuntu: sudo apt install dos2unix

---

Obtener Ayuda

Si sigues experimentando problemas:

1. Revisa los Issues de GitHub: github.com/affaan-m/everything-claude-code/issues
2. Habilita el Registro de Depuración:

   export CLAUDE_DEBUG=1
   export CLAUDE_LOG_LEVEL=debug
   

3. Recopila Información de Diagnóstico:

   claude --version
   node --version
   python3 --version
   echo $CLAUDE_PACKAGE_MANAGER
   ls -la ~/.claude/plugins/cache/
   

4. Abre un Issue: Incluye registros de depuración, mensajes de error e información de diagnóstico

---

Documentación Relacionada

• README.md - Instalación y funcionalidades
• CONTRIBUTING.md - Directrices de desarrollo
• docs/ - Documentación detallada
• examples/ - Ejemplos de uso