← Volver al listado de tecnologías ← Índice de Everything Claude Code

Capítulo 2: Instalación y Setup

17 de diciembre de 2024 Por: Artiko

claude-codeinstalacionpluginconfiguracion

Panorama general de la instalación

Everything Claude Code (ECC) es un conjunto de configuraciones, scripts, agentes, reglas y hooks que se integran con Claude Code CLI para transformar la herramienta base en un entorno de desarrollo profesional y altamente automatizado.

Antes de instalar cualquier componente, es fundamental entender qué va a suceder en tu sistema de archivos, cuáles son las dependencias reales, y qué nivel de control querés tener sobre la instalación.

Este capítulo cubre todo lo necesario para pasar de cero a una instalación completamente funcional, ya sea en macOS, Linux o Windows.

1. Prerequisitos Completos

1.1 Node.js

ECC requiere Node.js 18 o superior. La mayoría de los scripts usan sintaxis de ESModules modernos y APIs de Node.js que no están disponibles en versiones anteriores.

# Verificar versión instalada
node --version
# Debe mostrar v18.x.x o superior

# Si necesitás instalar/actualizar Node.js:
# macOS con nvm (recomendado)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20
nvm use 20
nvm alias default 20

# macOS con Homebrew
brew install node

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Arch Linux
sudo pacman -S nodejs npm

# Windows (con Chocolatey)
choco install nodejs

# Verificar npm también
npm --version

Por qué Node.js 18+: Los hooks de ECC usan fetch nativo (disponible desde Node.js 18), structuredClone, y otras APIs de la plataforma. En versiones anteriores los scripts fallan silenciosamente o con errores crípticos.

1.2 Claude Code CLI

ECC es una extensión de Claude Code, por lo que necesitás tener Claude Code instalado y funcionando antes de instalar ECC.

# Instalar Claude Code CLI
npm install -g @anthropic-ai/claude-code

# Verificar instalación
claude --version
# Debe mostrar 1.x.x o superior

# Verificar que podés ejecutar Claude Code
claude
# Debe abrir la sesión interactiva

Si todavía no tenés cuenta en Anthropic o API key configurada, seguí las instrucciones del capítulo anterior antes de continuar.

Versión mínima recomendada de Claude Code: 1.0.0. ECC usa el sistema de plugins, hooks y el formato de settings.json que se estabilizó en esta versión.

1.3 Git

Git es necesario para clonar el repositorio de ECC en la instalación manual, y también para que algunos hooks funcionen correctamente (el hook block-no-verify intercepta operaciones git).

# Verificar git
git --version
# Debe mostrar 2.x.x

# Instalar si no está disponible:
# macOS
brew install git

# Ubuntu/Debian
sudo apt-get install git

# Windows
winget install Git.Git

1.4 Package Managers soportados

ECC detecta y trabaja con los cuatro package managers más comunes del ecosistema JavaScript/TypeScript. Necesitás tener al menos uno instalado:

# npm (viene con Node.js)
npm --version

# pnpm (recomendado para performance)
npm install -g pnpm
pnpm --version

# yarn
npm install -g yarn
yarn --version

# bun (el más rápido)
curl -fsSL https://bun.sh/install | bash
bun --version

ECC usa el package manager correcto automáticamente según tu proyecto. No necesitás tenerlos todos instalados, solo el que uses.

1.5 Permisos necesarios

ECC instala archivos en tu directorio home (~/.claude/). No necesitás permisos de administrador para la instalación estándar.

# Verificar que tenés acceso de escritura a tu home
ls -la ~/.claude/
# Si no existe, créalo:
mkdir -p ~/.claude/agents ~/.claude/commands ~/.claude/rules ~/.claude/skills ~/.claude/hooks

# En Linux, verificar permisos
stat ~/.claude/
# User debe ser tu usuario

En Windows con WSL, los permisos del filesystem de Linux aplican normalmente. Para PowerShell nativo, puede ser necesario ajustar la política de ejecución de scripts:

# Windows PowerShell - habilitar scripts
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

1.6 Herramientas opcionales pero recomendadas

Algunos hooks y features de ECC funcionan mejor con estas herramientas instaladas:

# tmux (para el hook auto-tmux-dev)
# macOS
brew install tmux

# Ubuntu/Debian
sudo apt-get install tmux

# jq (para manipular JSON en scripts)
# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# ripgrep (para búsquedas más rápidas en proyectos grandes)
# macOS
brew install ripgrep

# Ubuntu/Debian
sudo apt-get install ripgrep

1.7 Resumen de prerequisitos

Componente	Versión mínima	Obligatorio	Notas
Node.js	18.0.0	Sí	Scripts de hooks
Claude Code CLI	1.0.0	Sí	Base del sistema
Git	2.0.0	Sí	Hooks git + clonado
npm	8.0.0	Sí	Viene con Node.js
tmux	cualquiera	No	Hook auto-dev-server
jq	1.6	No	Scripts JSON
ripgrep	cualquiera	No	Búsquedas optimizadas

2. Entendiendo la Estructura de Instalación

Antes de instalar, hay que entender dónde vive cada componente y cómo Claude Code los carga.

2.1 Dos ámbitos de configuración

Claude Code tiene dos ámbitos donde busca configuración:

Global (~/.claude/): Aplica a todas las sesiones de Claude Code en cualquier proyecto. Aquí van los componentes que querés disponibles siempre.

Por proyecto (.claude/ en la raíz del proyecto): Aplica solo cuando Claude Code se ejecuta desde ese directorio. Permite configuraciones específicas por proyecto que no interfieren con otros.

~/.claude/                    # Global - para todos los proyectos
├── settings.json             # Configuración principal, hooks
├── CLAUDE.md                 # Instrucciones globales
├── agents/                   # Agentes disponibles globalmente
├── commands/                 # Comandos slash globales
├── rules/                    # Reglas de codificación globales
├── skills/                   # Skills/capacidades globales
├── scripts/                  # Scripts de hooks
└── memory/                   # Archivos de memoria persistente

.claude/                      # Por proyecto (en raíz del proyecto)
├── settings.json             # Override de configuración local
├── CLAUDE.md                 # Instrucciones específicas del proyecto
├── agents/                   # Agentes solo para este proyecto
├── commands/                 # Comandos solo para este proyecto
└── rules/                    # Reglas específicas del proyecto

2.2 Jerarquía de carga y precedencia

Cuando Claude Code inicia una sesión, carga la configuración en este orden:

flowchart TD
    A[Claude Code inicia] --> B[Carga ~/.claude/settings.json]
    B --> C[Carga .claude/settings.json del proyecto]
    C --> D[Merge: proyecto sobreescribe global]
    D --> E[Carga reglas globales ~/.claude/rules/]
    E --> F[Carga reglas del proyecto .claude/rules/]
    F --> G[Registra agentes globales]
    G --> H[Registra agentes del proyecto]
    H --> I[Activa hooks del settings.json mergeado]
    I --> J[Sesión lista]

La precedencia importa: Si tenés el mismo hook en global y en proyecto, el comportamiento depende del tipo de merge. Para arrays como hooks, se concatenan. Para values escalares, el proyecto sobreescribe el global.

2.3 Qué instala ECC en cada ubicación

Cuando instalás ECC (por cualquier método), los componentes se distribuyen así:

Siempre en global (~/.claude/):

agents/ — Los agentes como spec-writer, test-writer, code-reviewer
commands/ — Comandos slash como /plan, /spec, /commit
rules/ — Reglas de codificación para tu lenguaje
scripts/ — Los scripts Node.js que ejecutan los hooks
settings.json — Se modifica para agregar los hooks

Opcional en proyecto (.claude/):

Rules específicas del proyecto
Comandos específicos del proyecto
Configuración de package manager del proyecto

2.4 El archivo settings.json

Este es el archivo central de configuración de Claude Code. ECC lo modifica para registrar los hooks. Su ubicación es ~/.claude/settings.json.

Estructura básica antes de ECC:

{
  "model": "claude-opus-4-5",
  "permissions": {
    "allow": [],
    "deny": []
  }
}

Estructura después de instalar ECC (veremos el detalle más adelante en la sección de hooks):

{
  "model": "claude-opus-4-5",
  "permissions": {
    "allow": [],
    "deny": []
  },
  "extraKnownMarketplaces": {
    "everything-claude-code": {
      "source": {
        "source": "github",
        "repo": "affaan-m/everything-claude-code"
      }
    }
  },
  "enabledPlugins": {
    "everything-claude-code@everything-claude-code": true
  },
  "hooks": {
    "PreToolUse": [...],
    "PostToolUse": [...],
    "SessionStart": [...],
    "PreCompact": [...]
  }
}

3. Opción 1: Instalación como Plugin (Recomendada)

La instalación como plugin es la forma más simple y se actualiza automáticamente cuando hay nuevas versiones de ECC. Es la opción recomendada para la mayoría de los usuarios.

3.1 Paso 1 — Registrar el marketplace

El sistema de plugins de Claude Code funciona con marketplaces. ECC tiene su propio marketplace en GitHub que hay que registrar primero.

Método A: Usando el comando /plugin en Claude Code

Abrí Claude Code y ejecutá:

/plugin marketplace add affaan-m/everything-claude-code

Claude Code va a confirmar que el marketplace fue agregado a tu settings.json.

Método B: Editando settings.json directamente

Si preferís editar el archivo directamente:

# Abrir settings.json (crear si no existe)
mkdir -p ~/.claude
nano ~/.claude/settings.json

Agregar la sección extraKnownMarketplaces:

{
  "extraKnownMarketplaces": {
    "everything-claude-code": {
      "source": {
        "source": "github",
        "repo": "affaan-m/everything-claude-code"
      }
    }
  }
}

Si ya tenés contenido en el archivo, mergear la sección extraKnownMarketplaces con el contenido existente. No reemplaces el archivo completo.

3.2 Paso 2 — Instalar el plugin

Con el marketplace registrado, instalá el plugin:

/plugin install everything-claude-code@everything-claude-code

Este comando:

Descarga el índice del marketplace desde GitHub
Resuelve las dependencias del plugin
Copia los componentes a ~/.claude/
Modifica settings.json para habilitar el plugin

Deberías ver output similar a:

Installing everything-claude-code@everything-claude-code...
✓ Downloading plugin manifest
✓ Installing agents (12 files)
✓ Installing commands (8 files)
✓ Installing scripts (23 files)
✓ Updating settings.json
Plugin installed successfully.

3.3 Paso 3 — Verificar que el plugin está habilitado

# En Claude Code
/plugin list

# Debe mostrar:
# everything-claude-code@everything-claude-code  [enabled]

También podés verificar en settings.json:

cat ~/.claude/settings.json | grep -A 3 "enabledPlugins"
# Debe mostrar:
# "enabledPlugins": {
#   "everything-claude-code@everything-claude-code": true
# }

3.4 Qué instala el plugin — Lista completa de componentes

El plugin instala los siguientes componentes en ~/.claude/:

Agentes (~/.claude/agents/):

Agente	Archivo	Propósito
Spec Writer	`spec-writer.md`	Crear especificaciones técnicas
Test Writer	`test-writer.md`	Generar tests unitarios e integración
Code Reviewer	`code-reviewer.md`	Revisar PRs y código
Debug Specialist	`debug-specialist.md`	Diagnóstico profundo de bugs
Architect	`architect.md`	Decisiones de arquitectura
Refactor Guide	`refactor-guide.md`	Refactoring seguro
Security Auditor	`security-auditor.md`	Auditoría de seguridad
Performance Analyst	`performance-analyst.md`	Análisis de performance
Documentation Writer	`docs-writer.md`	Documentación técnica
Migrator	`migrator.md`	Migraciones de código/DB
API Designer	`api-designer.md`	Diseño de APIs
Database Expert	`db-expert.md`	Optimización de queries y schema

Comandos (~/.claude/commands/):

Comando	Descripción
`/plan`	Planear implementación de features
`/spec`	Crear especificaciones
`/commit`	Commit inteligente con mensaje descriptivo
`/review`	Code review del diff actual
`/debug`	Iniciar sesión de debugging
`/refactor`	Refactoring guiado
`/test`	Generar tests
`/doc`	Generar documentación

Scripts de hooks (~/.claude/scripts/hooks/):

Script	Descripción
`auto-tmux-dev.js`	Iniciar servidores de desarrollo en tmux
`block-no-verify.js`	Bloquear bypass de git hooks
`config-protection.js`	Proteger archivos de configuración
`quality-gate.js`	Verificación de calidad post-edición
`post-edit-typecheck.js`	TypeScript check después de editar
`suggest-compact.js`	Sugerir compactación del contexto
`session-start.js`	Inicialización de sesión
`pre-compact.js`	Guardar estado antes de compactar
`run-with-flags.js`	Runner de hooks con perfiles

Utilidades (~/.claude/scripts/):

Script	Descripción
`setup-package-manager.js`	Configurar package manager del proyecto
`install-rules.js`	Instalar rules para un lenguaje
`validate-hooks.js`	Validar configuración de hooks

3.5 El settings.json completo post-instalación

Después de instalar el plugin, tu ~/.claude/settings.json va a lucir similar a esto. Analicemos cada sección:

{
  "model": "claude-opus-4-5",
  "permissions": {
    "allow": [],
    "deny": []
  },
  "extraKnownMarketplaces": {
    "everything-claude-code": {
      "source": {
        "source": "github",
        "repo": "affaan-m/everything-claude-code"
      }
    }
  },
  "enabledPlugins": {
    "everything-claude-code@everything-claude-code": true
  },
  "env": {
    "ECC_HOOK_PROFILE": "standard"
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "npx [email protected]"
          }
        ],
        "description": "Block git hook-bypass flag"
      },
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/auto-tmux-dev.js\""
          }
        ],
        "description": "Auto-start dev servers in tmux"
      },
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js\" \"pre:edit-write:suggest-compact\" \"scripts/hooks/suggest-compact.js\" \"standard,strict\""
          }
        ],
        "description": "Suggest manual compaction at logical intervals"
      },
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js\" \"pre:config-protection\" \"scripts/hooks/config-protection.js\" \"standard,strict\""
          }
        ],
        "description": "Block modifications to linter/formatter config files"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js\" \"post:quality-gate\" \"scripts/hooks/quality-gate.js\" \"standard,strict\"",
            "async": true,
            "timeout": 30
          }
        ],
        "description": "Run quality gate checks after file edits"
      },
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js\" \"post:edit:typecheck\" \"scripts/hooks/post-edit-typecheck.js\" \"strict\""
          }
        ],
        "description": "TypeScript check after editing .ts/.tsx files"
      }
    ],
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "bash -lc 'input=$(cat); node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js\" \"session:start\" \"scripts/hooks/session-start.js\" \"minimal,standard,strict\"'"
          }
        ],
        "description": "Load previous context and detect package manager on new session"
      }
    ],
    "PreCompact": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js\" \"pre:compact\" \"scripts/hooks/pre-compact.js\" \"standard,strict\""
          }
        ],
        "description": "Save state before context compaction"
      }
    ]
  }
}

Explicación de cada campo:

model: El modelo de Claude que se usa por defecto. Podés cambiarlo a claude-sonnet-4-5 para sesiones más rápidas y económicas.
permissions.allow: Lista de herramientas que Claude Code puede usar sin pedir confirmación.
permissions.deny: Lista de herramientas bloqueadas.
extraKnownMarketplaces: Registra el marketplace de ECC para poder instalar/actualizar el plugin.
enabledPlugins: Dict de plugins habilitados. true = habilitado.
env.ECC_HOOK_PROFILE: Perfil de severidad de hooks. minimal | standard | strict.
hooks: La sección principal de hooks, con cuatro eventos: PreToolUse, PostToolUse, SessionStart, PreCompact.

3.6 Instalar Rules (paso obligatorio adicional)

El sistema de plugins de Claude Code no puede distribuir rules automáticamente debido a cómo funciona el sistema de permisos. Las rules deben instalarse manualmente.

Las rules son archivos Markdown que le dicen a Claude Code cómo escribir código en tu lenguaje específico: convenciones de nombres, patrones preferidos, anti-patrones a evitar, etc.

# Clonar el repo de ECC (necesario para las rules)
git clone https://github.com/affaan-m/everything-claude-code.git ~/everything-claude-code-tmp
cd ~/everything-claude-code-tmp

# Ver qué lenguajes están disponibles
ls rules/
# typescript/  python/  golang/  swift/  php/  rust/  kotlin/  java/  cpp/  csharp/  perl/  common/

# Instalar rules para tu lenguaje(s)
./install.sh typescript
./install.sh python
./install.sh golang

# O instalar múltiples lenguajes a la vez
./install.sh typescript python golang

# Windows
.\install.ps1 typescript

El script install.sh copia los archivos de rules a ~/.claude/rules/ y también incluye las rules common/ que aplican a todos los lenguajes.

Para verificar que se instalaron:

ls ~/.claude/rules/
# Debe mostrar archivos .md de rules

4. Opción 2: Instalación Manual (Control Total)

La instalación manual te da control granular sobre exactamente qué componentes instalás. Es útil cuando:

Querés auditar cada archivo antes de instalarlo
Solo necesitás algunos componentes específicos
Estás en un entorno corporativo con restricciones de red
Querés modificar los componentes antes de instalarlos

4.1 Paso 1 — Clonar el repositorio

# Clonar en tu home o donde prefieras
git clone https://github.com/affaan-m/everything-claude-code.git ~/ecc
cd ~/ecc

# Verificar la estructura del repositorio
ls -la
# agents/     commands/     hooks/      mcp-configs/
# rules/      scripts/      skills/     install.sh
# install.ps1  CLAUDE.md    README.md

4.2 Paso 2 — Preparar directorios destino

# Crear todos los directorios necesarios
mkdir -p ~/.claude/agents
mkdir -p ~/.claude/commands
mkdir -p ~/.claude/rules
mkdir -p ~/.claude/skills
mkdir -p ~/.claude/scripts/hooks
mkdir -p ~/.claude/memory

4.3 Paso 3 — Instalar agentes

Los agentes son archivos Markdown con frontmatter YAML que definen un contexto especializado para Claude Code. Cada agente tiene un nombre, descripción, herramientas permitidas y opcionalmente un modelo específico.

# Ver qué agentes están disponibles
ls ~/ecc/agents/
# architect.md         api-designer.md      code-reviewer.md
# db-expert.md         debug-specialist.md  docs-writer.md
# migrator.md          performance-analyst.md  refactor-guide.md
# security-auditor.md  spec-writer.md       test-writer.md

# Copiar todos los agentes
cp ~/ecc/agents/*.md ~/.claude/agents/

# O copiar solo los que necesitás
cp ~/ecc/agents/spec-writer.md ~/.claude/agents/
cp ~/ecc/agents/test-writer.md ~/.claude/agents/
cp ~/ecc/agents/code-reviewer.md ~/.claude/agents/
cp ~/ecc/agents/debug-specialist.md ~/.claude/agents/

Qué hace cada agente:

Agente	Cuándo usarlo
`spec-writer`	Antes de implementar una feature nueva
`test-writer`	Para generar tests de código existente
`code-reviewer`	Para hacer review de cambios antes de PR
`debug-specialist`	Cuando un bug es difícil de reproducir o entender
`architect`	Para decisiones de arquitectura o refactors grandes
`refactor-guide`	Para refactors incrementales seguros
`security-auditor`	Antes de lanzar a producción
`performance-analyst`	Cuando hay problemas de performance
`docs-writer`	Para generar documentación técnica
`migrator`	Para migraciones de código, base de datos o framework
`api-designer`	Para diseñar APIs REST o GraphQL
`db-expert`	Para optimizar queries o diseñar schema

4.4 Paso 4 — Instalar rules por lenguaje

Las rules son el componente más importante para la calidad del código generado. Definen exactamente cómo Claude Code debe escribir código en tu lenguaje.

# Ver lenguajes disponibles
ls ~/ecc/rules/
# common/  typescript/  python/  golang/  swift/  php/
# rust/    kotlin/      java/    cpp/     csharp/ perl/

# Las rules 'common' siempre se instalan (aplican a todos los lenguajes)
cp -r ~/ecc/rules/common/* ~/.claude/rules/

# TypeScript/JavaScript
cp -r ~/ecc/rules/typescript/* ~/.claude/rules/

# Python
cp -r ~/ecc/rules/python/* ~/.claude/rules/

# Go
cp -r ~/ecc/rules/golang/* ~/.claude/rules/

# Swift (para desarrollo iOS/macOS)
cp -r ~/ecc/rules/swift/* ~/.claude/rules/

# PHP
cp -r ~/ecc/rules/php/* ~/.claude/rules/

# Rust
cp -r ~/ecc/rules/rust/* ~/.claude/rules/

# Kotlin (para Android o backend JVM)
cp -r ~/ecc/rules/kotlin/* ~/.claude/rules/

# Java
cp -r ~/ecc/rules/java/* ~/.claude/rules/

# C++
cp -r ~/ecc/rules/cpp/* ~/.claude/rules/

# C#
cp -r ~/ecc/rules/csharp/* ~/.claude/rules/

# Perl
cp -r ~/ecc/rules/perl/* ~/.claude/rules/

Nota: Si trabajás en proyectos políglotas (TypeScript en frontend + Python en backend, por ejemplo), podés instalar rules para múltiples lenguajes sin conflicto. Las rules de cada lenguaje aplican a los archivos del tipo correspondiente.

4.5 Paso 5 — Instalar comandos

Los comandos son los atajos slash que podés usar dentro de Claude Code para ejecutar flujos específicos.

# Copiar todos los comandos
cp ~/ecc/commands/*.md ~/.claude/commands/

# O copiar solo los esenciales
cp ~/ecc/commands/plan.md ~/.claude/commands/
cp ~/ecc/commands/spec.md ~/.claude/commands/
cp ~/ecc/commands/commit.md ~/.claude/commands/
cp ~/ecc/commands/review.md ~/.claude/commands/

4.6 Paso 6 — Instalar skills

Las skills son capacidades específicas que ECC añade a Claude Code. A diferencia de los agentes (que son contextos especializados), las skills son instrucciones procedurales para ejecutar tareas específicas.

# Ver skills disponibles
ls ~/ecc/skills/
# search-first/      tdd-workflow/       git-flow/
# code-review/       spec-driven/        debugging/
# refactoring/       api-design/         testing/

# Copiar las skills esenciales
cp -r ~/ecc/skills/search-first ~/.claude/skills/
cp -r ~/ecc/skills/tdd-workflow ~/.claude/skills/

# O copiar todas
cp -r ~/ecc/skills/* ~/.claude/skills/

Skills esenciales recomendadas:

Skill	Por qué es importante
`search-first`	Evita que Claude asuma; busca código existente primero
`tdd-workflow`	Workflow de Test-Driven Development
`git-flow`	Flujo de trabajo con git estructurado
`code-review`	Proceso de revisión de código sistemático
`spec-driven`	Desarrollo guiado por especificaciones

4.7 Paso 7 — Instalar scripts de hooks

Los scripts son el motor de los hooks. Sin ellos, los hooks en settings.json van a fallar.

# Copiar scripts de hooks
cp ~/ecc/scripts/hooks/*.js ~/.claude/scripts/hooks/

# Copiar scripts de utilidades
cp ~/ecc/scripts/*.js ~/.claude/scripts/

# Verificar que se copiaron
ls ~/.claude/scripts/hooks/
# auto-tmux-dev.js   block-no-verify.js   config-protection.js
# post-edit-typecheck.js  pre-compact.js  quality-gate.js
# run-with-flags.js  session-start.js     suggest-compact.js

4.8 Paso 8 — Configurar settings.json con hooks

Ahora necesitás agregar la configuración de hooks a tu ~/.claude/settings.json. Si el archivo no existe, créalo. Si ya existe, mergea las secciones.

# Crear settings.json básico si no existe
cat > ~/.claude/settings.json << 'EOF'
{
  "hooks": {
    "PreToolUse": [],
    "PostToolUse": [],
    "SessionStart": [],
    "PreCompact": []
  }
}
EOF

Luego, usando el editor de tu preferencia, agrega los hooks del archivo ~/ecc/hooks/hooks.json a tu settings.json. La próxima sección explica cada hook en detalle.

5. Instalación en macOS

macOS es el sistema más común para desarrollo con Claude Code. Hay diferencias menores entre Intel y Apple Silicon.

5.1 macOS con Homebrew (recomendado)

# Instalar Homebrew si no lo tenés
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Instalar dependencias
brew install git node
brew install tmux jq ripgrep  # opcionales pero recomendados

# Instalar bun (package manager rápido)
curl -fsSL https://bun.sh/install | bash

# Instalar Claude Code
npm install -g @anthropic-ai/claude-code

# Verificar
node --version  # v20.x.x
claude --version

5.2 macOS Apple Silicon (M1/M2/M3/M4)

En Apple Silicon, algunas herramientas nativas se instalan en /opt/homebrew en lugar de /usr/local. Los scripts de ECC usan node directamente, que funciona igual en ambas arquitecturas.

# Verificar arquitectura
uname -m
# arm64 = Apple Silicon
# x86_64 = Intel

# Homebrew en Apple Silicon se instala en /opt/homebrew
# Asegurarse de que está en el PATH
echo $PATH | grep homebrew

# Si no está, agregar al .zshrc
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc

# Verificar que node es arm64
file $(which node)
# Debe mostrar: Mach-O 64-bit executable arm64

5.3 macOS con nvm (gestión de versiones Node.js)

# Instalar nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Recargar shell
source ~/.zshrc

# Instalar Node.js LTS
nvm install --lts
nvm use --lts
nvm alias default node

# Verificar
node --version  # v20.x.x o v22.x.x

5.4 Permisos en macOS

macOS puede bloquear scripts descargados de internet. Si encontrás errores de permisos:

# Verificar permisos del script de instalación
ls -la ~/ecc/install.sh

# Dar permisos de ejecución
chmod +x ~/ecc/install.sh

# Si macOS bloquea por Gatekeeper
xattr -d com.apple.quarantine ~/ecc/install.sh

5.5 Integración con macOS Terminal y iTerm2

ECC detecta el terminal automáticamente. Para la mejor experiencia:

# Verificar que tmux está instalado (para el hook auto-tmux-dev)
tmux -V
# tmux 3.x.x

# Crear una configuración mínima de tmux si no tenés una
cat > ~/.tmux.conf << 'EOF'
set -g default-terminal "screen-256color"
set -g mouse on
set -g history-limit 10000
EOF

6. Instalación en Linux

ECC funciona perfectamente en todas las distribuciones Linux modernas.

6.1 Ubuntu y Debian

# Actualizar paquetes
sudo apt-get update

# Instalar dependencias base
sudo apt-get install -y git curl build-essential

# Instalar Node.js 20 (via NodeSource)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verificar
node --version
npm --version

# Instalar herramientas opcionales
sudo apt-get install -y tmux jq

# Instalar ripgrep
sudo apt-get install -y ripgrep

# Instalar bun
curl -fsSL https://bun.sh/install | bash

# Instalar Claude Code
npm install -g @anthropic-ai/claude-code

6.2 Arch Linux y Manjaro

# Instalar dependencias
sudo pacman -S git nodejs npm tmux jq ripgrep

# Instalar bun (via AUR o direct)
yay -S bun-bin
# O directamente:
curl -fsSL https://bun.sh/install | bash

# Instalar Claude Code
npm install -g @anthropic-ai/claude-code

6.3 Fedora y RHEL/CentOS

# Fedora
sudo dnf install -y git nodejs tmux jq

# RHEL/CentOS 8+
sudo dnf install -y git
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo dnf install -y nodejs

# Instalar ripgrep
sudo dnf install -y ripgrep

# Instalar bun
curl -fsSL https://bun.sh/install | bash

# Claude Code
npm install -g @anthropic-ai/claude-code

6.4 Configuración de PATH en Linux

En Linux, los paquetes globales de npm y bun pueden quedar fuera del PATH si no está configurado correctamente:

# Agregar al ~/.bashrc o ~/.zshrc según tu shell
# npm global
export PATH="$HOME/.npm-global/bin:$PATH"

# bun
export PATH="$HOME/.bun/bin:$PATH"

# Claude Code CLI (si se instaló con npm global)
export PATH="$(npm prefix -g)/bin:$PATH"

# Recargar
source ~/.bashrc
# O
source ~/.zshrc

6.5 Configuración de tmux en Linux

El hook auto-tmux-dev de ECC necesita tmux. Configuración básica:

# Verificar tmux
tmux -V

# Si vas a usar ECC en servidor remoto via SSH
# Habilitar que tmux inicie automaticamente
cat >> ~/.bashrc << 'EOF'
# Auto-start tmux on SSH
if [ -n "$SSH_CONNECTION" ] && [ -z "$TMUX" ]; then
  tmux attach-session -t main 2>/dev/null || tmux new-session -s main
fi
EOF

6.6 Entornos sin interfaz gráfica (servidores)

ECC funciona completamente en servidores headless. Los hooks de tmux son opcionales:

# Si no tenés tmux en el servidor, deshabilitar el hook
export ECC_DISABLED_HOOKS="pre:bash:auto-tmux-dev"

# Agregar al perfil para que persista
echo 'export ECC_DISABLED_HOOKS="pre:bash:auto-tmux-dev"' >> ~/.bashrc

7. Instalación en Windows

ECC tiene soporte oficial para Windows. Hay dos enfoques: PowerShell nativo y WSL (Windows Subsystem for Linux).

7.1 Recomendación: WSL2

Para la mejor experiencia en Windows, WSL2 es la opción recomendada. Claude Code y ECC se comportan exactamente igual que en Linux.

# En PowerShell como administrador
# Instalar WSL2 con Ubuntu
wsl --install -d Ubuntu-22.04

# Reiniciar cuando se solicite

# Abrir WSL
wsl

# Dentro de WSL, seguir las instrucciones de Ubuntu

Luego, dentro de WSL, seguí las instrucciones de la sección de Ubuntu.

7.2 Windows nativo con PowerShell

Si preferís no usar WSL, ECC también funciona en PowerShell:

# Instalar Chocolatey (si no lo tenés)
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# Instalar dependencias
choco install git nodejs-lts -y

# Verificar
node --version
git --version

# Instalar bun
powershell -c "irm bun.sh/install.ps1 | iex"

# Instalar Claude Code
npm install -g @anthropic-ai/claude-code

7.3 Script de instalación en Windows

ECC incluye install.ps1 para Windows:

# Clonar repo
git clone https://github.com/affaan-m/everything-claude-code.git $HOME\ecc
cd $HOME\ecc

# Ejecutar instalador de Windows
.\install.ps1 typescript
# O múltiples lenguajes
.\install.ps1 typescript python

7.4 Diferencias importantes en Windows

Rutas de archivos: En Windows, el directorio ~/.claude/ equivale a C:\Users\{username}\.claude\. Los scripts de ECC usan process.env.USERPROFILE para detectar el home en Windows.

Variables de entorno: En lugar de export, se usa $env: en PowerShell:

# Windows PowerShell
$env:ECC_HOOK_PROFILE = "standard"
$env:ECC_DISABLED_HOOKS = "pre:bash:auto-tmux-dev"

# Para persistir entre sesiones, agregar al perfil de PowerShell
Add-Content $PROFILE '$env:ECC_HOOK_PROFILE = "standard"'

tmux: tmux no está disponible de forma nativa en Windows PowerShell. El hook auto-tmux-dev se desactiva automáticamente en Windows. Si usás WSL, tmux funciona normalmente.

Saltos de línea: Si clonas el repo en Windows, asegurate de que git no convierta los saltos de línea:

git config --global core.autocrlf input

8. Configurar Hooks

Los hooks son el corazón de la automatización de ECC. Se ejecutan automáticamente en respuesta a eventos de Claude Code, sin necesidad de intervención manual.

8.1 Arquitectura del sistema de hooks

flowchart LR
    A[Claude Code Event] --> B{Tipo de evento}
    B -->|PreToolUse| C[Hook se ejecuta ANTES de la herramienta]
    B -->|PostToolUse| D[Hook se ejecuta DESPUÉS de la herramienta]
    B -->|SessionStart| E[Hook al iniciar sesión]
    B -->|PreCompact| F[Hook antes de compactar contexto]
    C --> G{Exit code}
    D --> H{Exit code}
    G -->|0| I[Herramienta ejecuta normalmente]
    G -->|!0| J[Herramienta BLOQUEADA]
    H -->|cualquiera| K[Continúa, output se loguea]

8.2 El hooks.json completo — sección por sección

El archivo hooks/hooks.json del repositorio de ECC contiene la configuración base. Analicemos cada parte:

Estructura raíz:

{
  "hooks": {
    "PreToolUse": [...],
    "PostToolUse": [...],
    "SessionStart": [...],
    "PreCompact": [...]
  }
}

Cada evento contiene un array de objetos con esta estructura:

{
  "matcher": "Bash",
  "hooks": [
    {
      "type": "command",
      "command": "...",
      "async": false,
      "timeout": 10
    }
  ],
  "description": "Descripción del hook"
}

matcher: Qué herramienta de Claude Code activa el hook. Puede ser un nombre exacto (Bash, Edit, Write) o un patrón regex (Edit|Write, *).
hooks[].type: Siempre "command" en la versión actual.
hooks[].command: El comando a ejecutar. Puede usar ${CLAUDE_PLUGIN_ROOT} como variable.
hooks[].async: Si true, el hook corre en background y no bloquea la herramienta.
hooks[].timeout: Segundos máximos antes de que el hook sea cancelado.

8.3 PreToolUse hooks — explicación detallada

Los hooks PreToolUse se ejecutan antes de que Claude Code use una herramienta. Si el hook retorna exit code distinto de 0, la herramienta es bloqueada.

Hook 1: block-no-verify

{
  "matcher": "Bash",
  "hooks": [
    {
      "type": "command",
      "command": "npx [email protected]"
    }
  ],
  "description": "Block git hook-bypass flag"
}

Este hook intercepta todos los comandos Bash que Claude Code intenta ejecutar. Si el comando incluye --no-verify (el flag que bypasea los git hooks de pre-commit y commit-msg), el hook falla con exit code 1, bloqueando el comando.

¿Por qué? Claude Code a veces intenta usar git commit --no-verify para evitar que fallen los hooks. Este comportamiento es inseguro porque bypasea validaciones importantes. block-no-verify asegura que los git hooks siempre se ejecuten.

Hook 2: auto-tmux-dev

{
  "matcher": "Bash",
  "hooks": [
    {
      "type": "command",
      "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/auto-tmux-dev.js\""
    }
  ],
  "description": "Auto-start dev servers in tmux"
}

Este hook analiza el comando Bash que Claude Code va a ejecutar. Si detecta un comando de servidor de desarrollo (npm run dev, bun dev, yarn start, etc.), lo redirige automáticamente a una ventana de tmux en background, evitando que bloquee el terminal de Claude Code.

Hook 3: suggest-compact

{
  "matcher": "Edit|Write",
  "hooks": [
    {
      "type": "command",
      "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js\" \"pre:edit-write:suggest-compact\" \"scripts/hooks/suggest-compact.js\" \"standard,strict\""
    }
  ],
  "description": "Suggest manual compaction at logical intervals"
}

Se activa antes de operaciones Edit o Write. Monitorea el crecimiento del contexto de la sesión y, cuando detecta que estás cerca del límite, sugiere usar /compact para comprimir el historial y liberar espacio de contexto.

Solo activo en perfiles standard y strict (no en minimal).

Hook 4: config-protection

{
  "matcher": "Write|Edit|MultiEdit",
  "hooks": [
    {
      "type": "command",
      "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js\" \"pre:config-protection\" \"scripts/hooks/config-protection.js\" \"standard,strict\""
    }
  ],
  "description": "Block modifications to linter/formatter config files"
}

Protege archivos de configuración de linters y formatters (.eslintrc, prettier.config.js, tsconfig.json, .pylintrc, etc.) de ser modificados por Claude Code sin confirmación explícita.

Si Claude Code intenta modificar un archivo de configuración, el hook lo bloquea y muestra un warning pidiendo confirmación explícita del usuario.

8.4 PostToolUse hooks — explicación detallada

Los hooks PostToolUse se ejecutan después de que Claude Code usa una herramienta. Su exit code no afecta si la herramienta se ejecutó o no (ya ocurrió), pero puede registrar información o emitir warnings.

Hook 5: quality-gate

{
  "matcher": "Edit|Write|MultiEdit",
  "hooks": [
    {
      "type": "command",
      "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js\" \"post:quality-gate\" \"scripts/hooks/quality-gate.js\" \"standard,strict\"",
      "async": true,
      "timeout": 30
    }
  ],
  "description": "Run quality gate checks after file edits"
}

Después de cualquier edición de archivo, este hook corre verificaciones de calidad:

Linting (si hay .eslintrc, pylint, golangci-lint, etc.)
Formato (prettier, black, gofmt, etc.)
Tests unitarios relacionados con el archivo editado

Es async: true para no bloquear el flujo de trabajo. Corre en background con un timeout de 30 segundos.

Hook 6: post-edit-typecheck

{
  "matcher": "Edit",
  "hooks": [
    {
      "type": "command",
      "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js\" \"post:edit:typecheck\" \"scripts/hooks/post-edit-typecheck.js\" \"strict\""
    }
  ],
  "description": "TypeScript check after editing .ts/.tsx files"
}

Solo activo en perfil strict. Después de editar archivos .ts o .tsx, ejecuta tsc --noEmit para verificar que no se introdujeron errores de tipos. Si hay errores, los reporta en el contexto de la sesión.

8.5 SessionStart hook — explicación detallada

{
  "matcher": "*",
  "hooks": [
    {
      "type": "command",
      "command": "bash -lc 'input=$(cat); node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js\" \"session:start\" \"scripts/hooks/session-start.js\" \"minimal,standard,strict\"'"
    }
  ],
  "description": "Load previous context and detect package manager on new session"
}

El matcher * significa que se activa para cualquier evento en SessionStart. Al iniciar cada nueva sesión de Claude Code:

Detecta el package manager del proyecto actual
Carga el contexto de la sesión anterior (si existe en ~/.claude/memory/)
Configura variables de entorno específicas del proyecto
Inyecta información del proyecto en el contexto inicial

Activo en todos los perfiles (minimal, standard, strict).

8.6 PreCompact hook — explicación detallada

{
  "matcher": "*",
  "hooks": [
    {
      "type": "command",
      "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js\" \"pre:compact\" \"scripts/hooks/pre-compact.js\" \"standard,strict\""
    }
  ],
  "description": "Save state before context compaction"
}

Se ejecuta justo antes de que Claude Code compacte el contexto (cuando el historial de la sesión se comprime para liberar espacio). Guarda el estado actual en ~/.claude/memory/ para que el hook SessionStart pueda recuperarlo en la próxima sesión.

8.7 Cómo agregar los hooks a settings.json

Si instalaste manualmente y necesitás agregar los hooks al settings.json:

# Método 1: Usar jq para mergear el hooks.json
jq -s '.[0] * .[1]' ~/.claude/settings.json ~/ecc/hooks/hooks.json > /tmp/settings-merged.json
mv /tmp/settings-merged.json ~/.claude/settings.json

# Método 2: Manual con editor
# Abrir settings.json y agregar la sección "hooks" del hooks.json de ECC
code ~/.claude/settings.json

Nota: El método con jq puede tener problemas si las claves no se mergean correctamente. Siempre verificá el resultado antes de reemplazar el archivo.

9. Configurar MCPs

Los Model Context Protocol servers (MCPs) extienden las capacidades de Claude Code con herramientas externas: búsqueda web, bases de datos, APIs, etc.

9.1 Qué es un MCP server

Un MCP server es un proceso que corre en background y expone herramientas adicionales a Claude Code a través del protocolo MCP. Claude Code puede entonces usar estas herramientas como si fueran propias.

9.2 El archivo mcp-servers.json de ECC

ECC incluye un archivo de referencia en mcp-configs/mcp-servers.json con configuraciones prearmadas para los MCPs más útiles.

# Ver qué MCPs incluye ECC
cat ~/ecc/mcp-configs/mcp-servers.json

Estructura típica:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"],
      "description": "File system access for specified directories"
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "YOUR_GITHUB_TOKEN_HERE"
      },
      "description": "GitHub API access"
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"],
      "description": "PostgreSQL database access"
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "YOUR_BRAVE_API_KEY_HERE"
      },
      "description": "Brave Search API"
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "description": "Real-time documentation lookup"
    }
  }
}

9.3 Agregar MCPs a tu configuración de Claude Code

La configuración de MCPs va en ~/.claude.json (con punto, diferente de ~/.claude/settings.json):

# Ver si ya existe
cat ~/.claude.json

# Si no existe o querés agregar los MCPs de ECC:
# Primero copiar el archivo base
cp ~/ecc/mcp-configs/mcp-servers.json /tmp/mcp-base.json

# Reemplazar los placeholders con tus API keys reales
sed -i 's/YOUR_GITHUB_TOKEN_HERE/ghp_tuTokenReal/g' /tmp/mcp-base.json
sed -i 's/YOUR_BRAVE_API_KEY_HERE/tu_brave_api_key/g' /tmp/mcp-base.json

# Mergear con tu claude.json existente
jq -s '.[0] * .[1]' ~/.claude.json /tmp/mcp-base.json > /tmp/claude-merged.json
mv /tmp/claude-merged.json ~/.claude.json

9.4 MCPs recomendados por ECC

MCP	Package	Qué hace	API Key necesaria
filesystem	`@modelcontextprotocol/server-filesystem`	Acceso a archivos del sistema	No
github	`@modelcontextprotocol/server-github`	GitHub API (repos, PRs, issues)	GITHUB_TOKEN
postgres	`@modelcontextprotocol/server-postgres`	Consultas a PostgreSQL	No (connection string)
brave-search	`@modelcontextprotocol/server-brave-search`	Búsqueda web	BRAVE_API_KEY
context7	`@upstash/context7-mcp`	Documentación actualizada de librerías	No
puppeteer	`@modelcontextprotocol/server-puppeteer`	Scraping y automatización web	No

9.5 Verificar que los MCPs funcionan

# Reiniciar Claude Code después de agregar MCPs
# Los MCPs se conectan al inicio de sesión

# En Claude Code, verificar herramientas disponibles
/tools
# Debe mostrar las herramientas de los MCPs configurados

9.6 Seguridad con API keys en MCPs

Nunca escribas API keys directamente en el archivo ~/.claude.json si lo vas a compartir o subir a control de versiones.

La forma segura es usar variables de entorno:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Y luego definir la variable en tu shell:

# ~/.zshrc o ~/.bashrc
export GITHUB_TOKEN="ghp_tuTokenReal"
export BRAVE_API_KEY="tu_brave_api_key_real"

10. Configurar Package Manager

ECC detecta automáticamente el package manager de tu proyecto para usar los comandos correctos (npm vs pnpm vs yarn vs bun).

10.1 Los 4 métodos de detección y su prioridad

ECC usa esta cascada de detección, de mayor a menor prioridad:

flowchart TD
    A[¿Variable ECC_HOOK_PROFILE definida?] -->|Sí| B[Usar ese package manager]
    A -->|No| C[¿Existe .claude/package-manager.json?]
    C -->|Sí| D[Leer y usar el value]
    C -->|No| E[¿package.json tiene campo packageManager?]
    E -->|Sí| F[Usar ese valor - ej: [email protected]]
    E -->|No| G[Detectar por lockfile]
    G --> H{¿Qué lockfile existe?}
    H -->|package-lock.json| I[npm]
    H -->|yarn.lock| J[yarn]
    H -->|pnpm-lock.yaml| K[pnpm]
    H -->|bun.lockb| L[bun]
    H -->|ninguno| M[npm por defecto]

10.2 Método 1 — Variable de entorno

La forma más rápida para override temporal:

# Para una sesión específica
export CLAUDE_PACKAGE_MANAGER=bun

# Verificar que está activo
echo $CLAUDE_PACKAGE_MANAGER

# Para deshabilitar y volver a autodetección
unset CLAUDE_PACKAGE_MANAGER

10.3 Método 2 — Archivo de configuración del proyecto

Para proyectos donde la detección automática no funciona bien:

# Crear directorio de configuración Claude del proyecto
mkdir -p .claude

# Crear archivo de configuración de package manager
cat > .claude/package-manager.json << 'EOF'
{
  "packageManager": "pnpm"
}
EOF

Este archivo debería commitearse al repositorio para que todos los miembros del equipo usen el mismo package manager.

10.4 Método 3 — Campo en package.json

El método estándar recomendado por Node.js:

{
  "name": "mi-proyecto",
  "version": "1.0.0",
  "packageManager": "[email protected]"
}

ECC lee este campo y extrae el nombre del package manager (pnpm en este caso).

10.5 Método 4 — Detección por lockfile

La detección automática funciona bien en la mayoría de los casos:

Lockfile	Package manager detectado
`package-lock.json`	npm
`yarn.lock`	yarn
`pnpm-lock.yaml`	pnpm
`bun.lockb`	bun
Ninguno	npm (fallback)

10.6 Usar el comando /setup-pm

ECC incluye un comando slash para configurar el package manager interactivamente:

/setup-pm

O desde la línea de comandos:

# Usando el script directamente
node ~/.claude/scripts/setup-package-manager.js --project bun

# Opciones disponibles
node ~/.claude/scripts/setup-package-manager.js --help

11. Hook Runtime Controls

Los Hook Runtime Controls permiten ajustar el comportamiento de los hooks sin editar el settings.json. Son útiles para situaciones específicas donde necesitás más o menos automatización.

11.1 Los 3 perfiles de severidad

ECC tiene tres perfiles predefinidos que controlan qué hooks están activos:

Perfil minimal:

Solo activa los hooks esenciales de seguridad. Ideal para sesiones de exploración o cuando trabajás en proyectos legacy que pueden tener muchos warnings.

Hooks activos en minimal:

session:start — Carga contexto de sesión anterior

Perfil standard (por defecto):

Balance entre automatización y no-intrusión. Activa la mayoría de los hooks excepto los más estrictos.

Hooks activos en standard (todo lo de minimal más):

pre:edit-write:suggest-compact — Sugerir compactación
pre:config-protection — Proteger configs
post:quality-gate — Quality gate asíncrono
pre:compact — Guardar estado pre-compactación

Perfil strict:

Todos los hooks activos. Máxima automatización y verificación. Ideal para proyectos críticos en producción.

Hooks activos en strict (todo lo de standard más):

post:edit:typecheck — TypeScript check en cada edición

11.2 Cambiar el perfil activo

# Para la sesión actual
export ECC_HOOK_PROFILE=minimal
export ECC_HOOK_PROFILE=standard
export ECC_HOOK_PROFILE=strict

# Para persistir el cambio
# En ~/.zshrc o ~/.bashrc
echo 'export ECC_HOOK_PROFILE=standard' >> ~/.zshrc
source ~/.zshrc

# También se puede configurar en settings.json para que sea el default
# Agregar en la sección "env" de settings.json:
# "env": { "ECC_HOOK_PROFILE": "standard" }

11.3 Deshabilitar hooks específicos

La variable ECC_DISABLED_HOOKS acepta una lista separada por comas de IDs de hooks a deshabilitar.

# Deshabilitar un hook específico
export ECC_DISABLED_HOOKS="pre:bash:auto-tmux-dev"

# Deshabilitar múltiples hooks
export ECC_DISABLED_HOOKS="pre:bash:auto-tmux-dev,post:edit:typecheck"

# Deshabilitar todos los hooks de calidad
export ECC_DISABLED_HOOKS="post:quality-gate,post:edit:typecheck"

IDs de hooks disponibles para deshabilitar:

ID	Hook deshabilitado
`pre:bash:auto-tmux-dev`	Auto-start de servidores en tmux
`pre:bash:block-no-verify`	Bloqueo de —no-verify
`pre:edit-write:suggest-compact`	Sugerencia de compactación
`pre:config-protection`	Protección de archivos de config
`post:quality-gate`	Quality gate asíncrono
`post:edit:typecheck`	TypeScript check post-edición
`session:start`	Inicialización de sesión
`pre:compact`	Guardado pre-compactación

11.4 Variables de entorno completas de ECC

Variable	Valores	Descripción
`ECC_HOOK_PROFILE`	`minimal`, `standard`, `strict`	Perfil de severidad de hooks
`ECC_DISABLED_HOOKS`	IDs separados por coma	Hooks específicos a deshabilitar
`CLAUDE_PACKAGE_MANAGER`	`npm`, `pnpm`, `yarn`, `bun`	Override del package manager
`CLAUDE_PLUGIN_ROOT`	ruta absoluta	Raíz del plugin (set automáticamente)

11.5 Inyección dinámica de system prompt

Una técnica avanzada que se complementa con ECC es la inyección dinámica de system prompt para diferentes contextos de trabajo:

# Crear archivos de contexto
mkdir -p ~/.claude/contexts

# Contexto de desarrollo
cat > ~/.claude/contexts/dev.md << 'EOF'
You are helping with active development. Focus on:
- Writing clean, tested code
- Following existing patterns in the codebase
- Suggesting optimizations when relevant
EOF

# Contexto de review
cat > ~/.claude/contexts/review.md << 'EOF'
You are doing a thorough code review. Focus on:
- Security vulnerabilities
- Performance issues
- Code style and consistency
- Missing tests
EOF

# Aliases para usar contextos específicos
alias claude-dev='claude --system-prompt "$(cat ~/.claude/contexts/dev.md)"'
alias claude-review='claude --system-prompt "$(cat ~/.claude/contexts/review.md)"'
alias claude-security='claude --system-prompt "$(cat ~/.claude/contexts/security.md)"'

12. Verificación Completa de la Instalación

Después de instalar ECC, usá este checklist de verificación para confirmar que todo está funcionando correctamente.

12.1 Checklist de verificación

# 1. Verificar Node.js
node --version  # ✓ v18.x.x o superior

# 2. Verificar Claude Code CLI
claude --version  # ✓ 1.x.x o superior

# 3. Verificar que settings.json existe y tiene hooks
cat ~/.claude/settings.json | python3 -m json.tool > /dev/null && echo "✓ settings.json válido"

# 4. Verificar que hay hooks configurados
cat ~/.claude/settings.json | grep -c '"PreToolUse"'  # ✓ 1

# 5. Verificar scripts de hooks
ls ~/.claude/scripts/hooks/*.js | wc -l  # ✓ 9 archivos o más

# 6. Verificar agentes
ls ~/.claude/agents/*.md | wc -l  # ✓ 12 archivos o más

# 7. Verificar comandos
ls ~/.claude/commands/*.md | wc -l  # ✓ 8 archivos o más

# 8. Verificar rules
ls ~/.claude/rules/*.md | wc -l  # ✓ 5+ archivos (según lenguajes instalados)

# 9. Verificar skills
ls ~/.claude/skills/ | wc -l  # ✓ 5+ directorios

# 10. Verificar que run-with-flags.js funciona
node ~/.claude/scripts/hooks/run-with-flags.js --help  # ✓ sin errores

# 11. Verificar variable ECC_HOOK_PROFILE
echo ${ECC_HOOK_PROFILE:-standard}  # ✓ minimal|standard|strict

# 12. Verificar git
git --version  # ✓ 2.x.x

# 13. Verificar tmux (opcional)
tmux -V  # ✓ tmux 3.x.x (o "command not found" si es opcional)

# 14. Verificar que Claude Code carga los hooks
# Iniciar una sesión de Claude Code y verificar que SessionStart hook se ejecuta
# (verás output del hook en los logs)

# 15. Verificar el hook block-no-verify
# En Claude Code, intentar ejecutar: git commit --no-verify
# Debe ser bloqueado con un mensaje de error

# 16. Verificar que los comandos slash funcionan
# En Claude Code: /plan "Test installation"
# Debe ejecutarse sin error

# 17. Verificar agentes
# En Claude Code: /spec-writer
# Debe cambiar al contexto del agente spec-writer

# 18. Verificar package manager detection
# En un proyecto con package-lock.json:
# node ~/.claude/scripts/setup-package-manager.js --detect
# Debe mostrar: "Detected: npm"

# 19. Verificar MCP servers (si configuraste)
# En Claude Code: /tools
# Debe listar herramientas de los MCPs configurados

# 20. Verificar que settings.json es JSON válido
python3 -c "import json; json.load(open('${HOME}/.claude/settings.json'))" && echo "✓ JSON válido"

12.2 Test de smoke rápido

Para una verificación rápida de los componentes principales:

# Ejecutar en terminal
echo "=== ECC Installation Smoke Test ==="
echo ""
echo -n "Node.js: "
node --version 2>/dev/null || echo "❌ No encontrado"

echo -n "Claude Code: "
claude --version 2>/dev/null || echo "❌ No encontrado"

echo -n "settings.json: "
[ -f ~/.claude/settings.json ] && echo "✓ Existe" || echo "❌ No encontrado"

echo -n "Hooks configurados: "
grep -q "PreToolUse" ~/.claude/settings.json 2>/dev/null && echo "✓ Sí" || echo "❌ No"

echo -n "Scripts de hooks: "
[ -d ~/.claude/scripts/hooks ] && ls ~/.claude/scripts/hooks/*.js 2>/dev/null | wc -l | xargs echo "archivos" || echo "❌ No encontrado"

echo -n "Agentes: "
[ -d ~/.claude/agents ] && ls ~/.claude/agents/*.md 2>/dev/null | wc -l | xargs echo "agentes" || echo "❌ No encontrado"

echo -n "Rules: "
[ -d ~/.claude/rules ] && ls ~/.claude/rules/*.md 2>/dev/null | wc -l | xargs echo "rules" || echo "❌ No encontrado"

echo ""
echo "=== Smoke test completado ==="

13. Troubleshooting

13.1 Error: “node: command not found” en hooks

Síntoma: Al usar Claude Code, los hooks fallan con node: command not found o command not found: node.

Causa: El PATH del shell que ejecuta los hooks no incluye el directorio donde está instalado Node.js. Esto ocurre frecuentemente cuando Node.js se instaló con nvm o en una ruta no estándar.

Solución:

# 1. Encontrar dónde está node
which node
# Ej: /home/user/.nvm/versions/node/v20.11.0/bin/node

# 2. Usar la ruta absoluta en settings.json
# Editar los hooks para usar /home/user/.nvm/versions/node/v20.11.0/bin/node
# en lugar de solo "node"

# 3. O mejor, usar bash -lc para cargar el profile completo
# Modificar el comando del hook a:
# "bash -lc 'node /ruta/al/script.js'"

# 4. Alternativa: agregar symlink en /usr/local/bin
sudo ln -sf $(which node) /usr/local/bin/node

13.2 Error: “CLAUDE_PLUGIN_ROOT is not defined”

Síntoma: Los hooks fallan con Error: Cannot find module o variables no definidas relacionadas con CLAUDE_PLUGIN_ROOT.

Causa: La variable CLAUDE_PLUGIN_ROOT la setea Claude Code cuando usa el sistema de plugins. En instalación manual, no está definida automáticamente.

Solución:

# En instalación manual, definir la variable manualmente
export CLAUDE_PLUGIN_ROOT="$HOME/.claude"

# Agregar al .zshrc o .bashrc para que persista
echo 'export CLAUDE_PLUGIN_ROOT="$HOME/.claude"' >> ~/.zshrc
source ~/.zshrc

# Verificar
echo $CLAUDE_PLUGIN_ROOT
# /home/user/.claude

13.3 Error: “settings.json is not valid JSON”

Síntoma: Claude Code no carga la configuración y muestra un error de JSON inválido.

Causa: El archivo settings.json tiene un error de sintaxis, generalmente una coma extra o faltante, o llaves desbalanceadas.

Solución:

# Validar el JSON
python3 -c "import json; json.load(open('$HOME/.claude/settings.json'))"
# Mostrará la línea y columna del error

# O con jq
jq . ~/.claude/settings.json
# Mostrará el error con más detalle

# Reparar manualmente con editor
code ~/.claude/settings.json

# Como último recurso, resetear settings.json
cp ~/.claude/settings.json ~/.claude/settings.json.bak
cat > ~/.claude/settings.json << 'EOF'
{
  "hooks": {}
}
EOF
# Luego volver a agregar los hooks

13.4 Error: “Permission denied” al ejecutar scripts

Síntoma: Los hooks fallan con Permission denied o EACCES.

Causa: Los scripts de hooks no tienen permisos de ejecución.

Solución:

# Dar permisos a todos los scripts
chmod +x ~/.claude/scripts/**/*.js
chmod +x ~/.claude/scripts/*.js

# En macOS, puede ser necesario quitar la quarantine flag
find ~/.claude/scripts -name "*.js" -exec xattr -d com.apple.quarantine {} \; 2>/dev/null

13.5 El hook block-no-verify bloquea comandos legítimos

Síntoma: Claude Code no puede ejecutar ciertos comandos git porque el hook los bloquea incorrectamente.

Causa: El hook block-no-verify puede tener falsos positivos con algunos patrones de comando.

Solución:

# Deshabilitar temporalmente
export ECC_DISABLED_HOOKS="pre:bash:block-no-verify"

# O deshabilitar permanentemente si no lo necesitás
echo 'export ECC_DISABLED_HOOKS="${ECC_DISABLED_HOOKS:+$ECC_DISABLED_HOOKS,}pre:bash:block-no-verify"' >> ~/.zshrc

13.6 Los servidores de desarrollo no se inician en tmux

Síntoma: El hook auto-tmux-dev no redirige los servidores de desarrollo a tmux, o tmux no se encuentra.

Causa A: tmux no está instalado.

# Verificar
which tmux
# Instalar si no está
# macOS: brew install tmux
# Ubuntu: sudo apt-get install tmux

Causa B: tmux está instalado pero no en el PATH del hook.

# Verificar PATH del hook
bash -lc 'which tmux'

# Si tmux está en una ruta no estándar, agregar al PATH en .bashrc/.zshrc
export PATH="/usr/local/bin:$PATH"

Causa C: No hay sesión de tmux activa.

# Crear una sesión de tmux antes de usar Claude Code
tmux new-session -d -s claude-session

13.7 El quality-gate falla pero el código está correcto

Síntoma: El hook quality-gate reporta errores después de editar archivos, pero el código parece correcto.

Causa: Las herramientas de linting o formato no están instaladas en el proyecto, o la configuración del linter tiene reglas conflictivas.

Solución:

# Verificar qué herramientas espera el quality-gate
cat ~/.claude/scripts/hooks/quality-gate.js | grep -A 5 "tools"

# Instalar las herramientas faltantes
npm install --save-dev eslint prettier typescript

# O cambiar a perfil minimal para deshabilitar quality-gate
export ECC_HOOK_PROFILE=minimal

# O deshabilitar solo quality-gate
export ECC_DISABLED_HOOKS="post:quality-gate"

13.8 El TypeScript check es muy lento

Síntoma: Después de editar archivos TypeScript, hay una pausa notable antes de poder continuar (el hook post-edit-typecheck está bloqueando).

Causa: tsc --noEmit en proyectos grandes puede tardar 10-30 segundos.

Solución:

# Opción 1: Cambiar de perfil strict a standard (desactiva typecheck)
export ECC_HOOK_PROFILE=standard

# Opción 2: Deshabilitar solo el typecheck
export ECC_DISABLED_HOOKS="post:edit:typecheck"

# Opción 3: Usar tsc --incremental para builds más rápidas
# En tsconfig.json agregar:
# "incremental": true,
# "tsBuildInfoFile": ".tsbuildinfo"

13.9 Error: “Cannot find module” al ejecutar hooks

Síntoma: Los hooks fallan con Error: Cannot find module '/path/to/script.js'.

Causa: Los scripts no se copiaron a la ubicación correcta, o CLAUDE_PLUGIN_ROOT apunta al lugar equivocado.

Solución:

# Verificar CLAUDE_PLUGIN_ROOT
echo $CLAUDE_PLUGIN_ROOT

# Verificar que los scripts están en esa ubicación
ls $CLAUDE_PLUGIN_ROOT/scripts/hooks/

# Si la ruta es incorrecta, corregir
export CLAUDE_PLUGIN_ROOT="$HOME/.claude"

# Re-copiar scripts si faltan
cp ~/ecc/scripts/hooks/*.js ~/.claude/scripts/hooks/

13.10 El SessionStart hook no carga el contexto anterior

Síntoma: Al iniciar una nueva sesión, el contexto de la sesión anterior no se recupera.

Causa A: La primera sesión no guardó el contexto porque el hook pre:compact no se ejecutó.

Causa B: El directorio de memoria no existe.

# Crear directorio de memoria
mkdir -p ~/.claude/memory

# Verificar que hay archivos de memoria
ls ~/.claude/memory/

# Si está vacío, es normal en la primera sesión

13.11 Los comandos slash no aparecen en Claude Code

Síntoma: Al escribir /plan o /spec en Claude Code, no aparecen como sugerencias ni se ejecutan.

Causa: Los archivos de comandos no están en el directorio correcto o tienen errores de formato.

Solución:

# Verificar que los comandos están instalados
ls ~/.claude/commands/

# Verificar formato de un comando
cat ~/.claude/commands/plan.md
# Debe empezar con frontmatter YAML válido

# Verificar que Claude Code carga los comandos
# En Claude Code: /help
# Debe listar todos los comandos disponibles

13.12 Conflictos con configuración de git global

Síntoma: El hook block-no-verify interfiere con flujos de trabajo de git personalizados.

Causa: El hook es demasiado agresivo para ciertos casos de uso.

Solución:

# Ver qué exactamente bloquea
npx [email protected] -- git commit --no-verify -m "test"

# Si necesitás hacer commits sin verify en casos específicos:
# 1. Deshabilitar temporalmente el hook
export ECC_DISABLED_HOOKS="pre:bash:block-no-verify"

# 2. Hacer el commit directamente en terminal (no desde Claude Code)
git commit --no-verify -m "tu mensaje"

# 3. Re-habilitar
unset ECC_DISABLED_HOOKS

13.13 Error en Windows: scripts de PowerShell bloqueados

Síntoma: Al ejecutar install.ps1 en Windows, aparece un error de política de ejecución.

Causa: La política de ejecución de PowerShell bloquea scripts no firmados.

Solución:

# Ver política actual
Get-ExecutionPolicy

# Cambiar política para el usuario actual
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

# Re-ejecutar el script
.\install.ps1 typescript

# Restaurar política restrictiva después
Set-ExecutionPolicy Restricted -Scope CurrentUser

13.14 Los MCPs no se conectan

Síntoma: Las herramientas de MCP no aparecen disponibles en Claude Code.

Causa A: ~/.claude.json tiene errores de sintaxis.

python3 -c "import json; json.load(open('$HOME/.claude.json'))"

Causa B: El package del MCP no está instalado.

# Instalar manualmente para verificar
npx -y @modelcontextprotocol/server-filesystem /tmp

# Si falla, instalar globalmente
npm install -g @modelcontextprotocol/server-filesystem

Causa C: La API key es incorrecta o expiró.

# Verificar que la variable de entorno está definida
echo $GITHUB_TOKEN
echo $BRAVE_API_KEY

13.15 El hook suggest-compact es muy frecuente

Síntoma: El hook suggest-compact interrumpe constantemente el trabajo sugiriendo compactación.

Causa: El umbral de contexto está configurado para sesiones más cortas.

Solución:

# Opción 1: Cambiar a perfil minimal
export ECC_HOOK_PROFILE=minimal

# Opción 2: Deshabilitar solo suggest-compact
export ECC_DISABLED_HOOKS="pre:edit-write:suggest-compact"

# Opción 3: Modificar el script para aumentar el umbral
# Editar ~/.claude/scripts/hooks/suggest-compact.js
# Buscar el threshold y aumentarlo

14. Actualizar ECC

14.1 Actualizar via plugin

Si instalaste ECC como plugin, la actualización es simple:

# En Claude Code
/plugin update everything-claude-code@everything-claude-code

# O desinstalar y reinstalar
/plugin uninstall everything-claude-code@everything-claude-code
/plugin install everything-claude-code@everything-claude-code

14.2 Actualizar instalación manual

# Ir al directorio clonado
cd ~/ecc

# Obtener cambios
git pull origin main

# Re-copiar componentes actualizados
cp agents/*.md ~/.claude/agents/
cp commands/*.md ~/.claude/commands/
cp -r scripts/hooks/*.js ~/.claude/scripts/hooks/
cp -r scripts/*.js ~/.claude/scripts/

# Re-ejecutar install.sh para actualizar rules
./install.sh typescript  # tu(s) lenguaje(s)

14.3 Verificar qué versión tenés

# En el repo clonado
cd ~/ecc
git log --oneline -5

# Ver la versión en el package.json del repo
cat ~/ecc/package.json | python3 -c "import json,sys; print(json.load(sys.stdin).get('version', 'N/A'))"

14.4 Migraciones entre versiones

Cuando hay cambios breaking en ECC (cambios en el formato de hooks, nombres de scripts, etc.), el repositorio incluye notas de migración en CHANGELOG.md:

# Ver cambios recientes
cat ~/ecc/CHANGELOG.md | head -100

15. Desinstalar ECC

15.1 Desinstalar el plugin

# En Claude Code
/plugin uninstall everything-claude-code@everything-claude-code

# También remover el marketplace del settings.json (opcional)
# Editar ~/.claude/settings.json y remover la sección extraKnownMarketplaces

15.2 Desinstalar componentes manualmente

Si instalaste manualmente o querés limpiar después de desinstalar el plugin:

# Remover agentes de ECC (cuidado de no borrar los tuyos propios)
rm ~/.claude/agents/spec-writer.md
rm ~/.claude/agents/test-writer.md
# ... etc

# Remover comandos
rm ~/.claude/commands/plan.md
# ... etc

# Remover scripts de hooks
rm -rf ~/.claude/scripts/hooks/
rm -rf ~/.claude/scripts/

# Remover rules (cuidado con las rules propias)
rm ~/.claude/rules/*.md

# Remover skills de ECC
rm -rf ~/.claude/skills/search-first
rm -rf ~/.claude/skills/tdd-workflow
# ... etc

15.3 Limpiar settings.json

Remover los hooks de ECC del settings.json:

# Hacer backup primero
cp ~/.claude/settings.json ~/.claude/settings.json.bak

# Editar y remover la sección "hooks" de ECC
code ~/.claude/settings.json
# O nano ~/.claude/settings.json

# Validar que quedó válido
python3 -c "import json; json.load(open('$HOME/.claude/settings.json'))" && echo "✓ OK"

16. Configuración Mínima vs Configuración Completa

No todos los proyectos necesitan la instalación completa de ECC. Esta sección ayuda a elegir qué instalar según el caso de uso.

16.1 Configuración mínima (individual, proyectos personales)

Para un desarrollador solo trabajando en proyectos personales:

Instalar:

✓ Rules para tu lenguaje principal
✓ Comandos: /plan, /commit
✓ Hooks: solo block-no-verify y session-start
✓ Perfil: minimal

No necesitás:

× Todos los agentes especializados
× Quality gate (no hay equipo que mantener)
× TypeScript strict check (overhead innecesario en exploración)
× MCPs complejos

# Instalación mínima
cp ~/ecc/commands/plan.md ~/.claude/commands/
cp ~/ecc/commands/commit.md ~/.claude/commands/
cp -r ~/ecc/rules/common/* ~/.claude/rules/
cp -r ~/ecc/rules/typescript/* ~/.claude/rules/
cp ~/ecc/scripts/hooks/session-start.js ~/.claude/scripts/hooks/
cp ~/ecc/scripts/hooks/run-with-flags.js ~/.claude/scripts/hooks/
export ECC_HOOK_PROFILE=minimal

16.2 Configuración estándar (equipo pequeño)

Para equipos de 2-5 personas en un proyecto activo:

Instalar todo más:

✓ Todos los agentes relevantes al stack
✓ Comandos: /plan, /spec, /commit, /review
✓ Todos los hooks en perfil standard
✓ Quality gate con linting del proyecto
✓ Skills: search-first, tdd-workflow, code-review

16.3 Configuración completa (equipos grandes, producción)

Para equipos grandes o proyectos de producción críticos:

Instalar todo:

✓ Todos los agentes
✓ Todos los comandos
✓ Todos los hooks en perfil strict
✓ TypeScript check en cada edición
✓ MCPs: github, filesystem, context7
✓ Skills: todas
✓ Configuración por proyecto en .claude/

16.4 Recomendaciones por tipo de proyecto

Tipo de proyecto	Perfil	Agentes esenciales	Hooks esenciales
Prototipo/exploración	minimal	ninguno	session-start
App web frontend	standard	spec-writer, test-writer	quality-gate, config-protection
API backend	standard	spec-writer, api-designer, db-expert	quality-gate, typecheck
Sistema crítico	strict	todos	todos
Open source	standard	code-reviewer, docs-writer	block-no-verify, quality-gate
Mobile (iOS/Android)	standard	spec-writer, test-writer	quality-gate

17. Ejercicios Prácticos

Los siguientes ejercicios te van a ayudar a verificar y familiarizarte con la instalación de ECC.

Ejercicio 1 — Verificación de prerequisitos

Objetivo: Confirmar que todos los prerequisitos están correctamente instalados.

# Ejecutar cada comando y verificar el output esperado

# 1. Verificar Node.js
node --version
# Expected: v18.x.x, v20.x.x, o v22.x.x

# 2. Verificar npm
npm --version
# Expected: 8.x.x o superior

# 3. Verificar git
git --version
# Expected: 2.x.x

# 4. Verificar Claude Code
claude --version
# Expected: 1.x.x

# 5. Verificar que claude funciona
echo '{"role": "user", "content": "Responde solo: OK"}' | claude --print-output-format json
# Expected: JSON con "OK" en el contenido

Anota los resultados. Si alguno falla, revisá la sección de prerequisitos antes de continuar.

Ejercicio 2 — Instalación manual de un solo componente

Objetivo: Entender el proceso de instalación instalando solo las rules de TypeScript.

# 1. Clonar el repositorio
git clone https://github.com/affaan-m/everything-claude-code.git /tmp/ecc-test

# 2. Verificar la estructura
ls /tmp/ecc-test/rules/

# 3. Crear directorio de rules si no existe
mkdir -p ~/.claude/rules

# 4. Instalar solo las rules de TypeScript
cp -r /tmp/ecc-test/rules/common/* ~/.claude/rules/
cp -r /tmp/ecc-test/rules/typescript/* ~/.claude/rules/

# 5. Verificar instalación
ls ~/.claude/rules/
# Debe mostrar archivos .md

# 6. Ver contenido de una rule
cat ~/.claude/rules/$(ls ~/.claude/rules/ | head -1)

# 7. Limpiar
rm -rf /tmp/ecc-test

Ejercicio 3 — Configurar un hook manualmente

Objetivo: Entender cómo funciona el sistema de hooks añadiendo un hook simple.

# 1. Hacer backup de settings.json
cp ~/.claude/settings.json ~/.claude/settings.json.ejercicio3.bak

# 2. Verificar settings.json actual
cat ~/.claude/settings.json

# 3. Agregar un hook PreToolUse simple usando Python
python3 << 'EOF'
import json

with open(f"{__import__('os').path.expanduser('~')}/.claude/settings.json", 'r') as f:
    settings = json.load(f)

# Agregar sección hooks si no existe
if 'hooks' not in settings:
    settings['hooks'] = {}
if 'PreToolUse' not in settings['hooks']:
    settings['hooks']['PreToolUse'] = []

# Agregar un hook de ejemplo
test_hook = {
    "matcher": "Bash",
    "hooks": [
        {
            "type": "command",
            "command": "echo 'Hook ejecutado: PreToolUse/Bash'"
        }
    ],
    "description": "Hook de prueba - Ejercicio 3"
}

settings['hooks']['PreToolUse'].append(test_hook)

with open(f"{__import__('os').path.expanduser('~')}/.claude/settings.json", 'w') as f:
    json.dump(settings, f, indent=2)

print("Hook agregado correctamente")
EOF

# 4. Verificar que se agregó
cat ~/.claude/settings.json | python3 -m json.tool | grep -A 5 "Hook de prueba"

# 5. Probar: en Claude Code, ejecutar cualquier comando bash
# Deberías ver "Hook ejecutado: PreToolUse/Bash" en el output

# 6. Limpiar (restaurar backup)
cp ~/.claude/settings.json.ejercicio3.bak ~/.claude/settings.json

Ejercicio 4 — Probar Hook Runtime Controls

Objetivo: Practicar el cambio de perfiles y la deshabilitación de hooks específicos.

# 1. Ver el perfil actual
echo "Perfil actual: ${ECC_HOOK_PROFILE:-standard}"

# 2. Cambiar a minimal
export ECC_HOOK_PROFILE=minimal
echo "Nuevo perfil: $ECC_HOOK_PROFILE"

# 3. Deshabilitar un hook específico
export ECC_DISABLED_HOOKS="pre:bash:auto-tmux-dev"
echo "Hooks deshabilitados: $ECC_DISABLED_HOOKS"

# 4. Ver el estado completo de configuración
echo "=== ECC Runtime Configuration ==="
echo "Profile: ${ECC_HOOK_PROFILE:-standard}"
echo "Disabled hooks: ${ECC_DISABLED_HOOKS:-ninguno}"
echo "Package manager: ${CLAUDE_PACKAGE_MANAGER:-autodetect}"

# 5. Restaurar defaults
unset ECC_HOOK_PROFILE
unset ECC_DISABLED_HOOKS
echo "Configuración restaurada a defaults"

Ejercicio 5 — Verificar detección de package manager

Objetivo: Entender cómo ECC detecta el package manager de un proyecto.

# 1. Crear un directorio de prueba
mkdir /tmp/pm-test-ecc
cd /tmp/pm-test-ecc

# 2. Test con npm (package-lock.json)
touch package-lock.json
node ~/.claude/scripts/setup-package-manager.js --detect
# Esperado: npm

# 3. Test con pnpm (pnpm-lock.yaml)
rm package-lock.json
touch pnpm-lock.yaml
node ~/.claude/scripts/setup-package-manager.js --detect
# Esperado: pnpm

# 4. Test con variable de entorno (override)
export CLAUDE_PACKAGE_MANAGER=bun
node ~/.claude/scripts/setup-package-manager.js --detect
# Esperado: bun (ignorar el pnpm-lock.yaml)
unset CLAUDE_PACKAGE_MANAGER

# 5. Test con package.json
rm pnpm-lock.yaml
echo '{"name":"test","packageManager":"[email protected]"}' > package.json
node ~/.claude/scripts/setup-package-manager.js --detect
# Esperado: yarn

# 6. Limpiar
cd ~
rm -rf /tmp/pm-test-ecc

18. Checklist Final

Usá esta lista de verificación completa para confirmar que tu instalación de ECC está completa y funcionando.

Pre-instalación

Node.js v18+ instalado y en PATH
Claude Code CLI instalado y configurado con API key
Git instalado
Al menos un package manager disponible (npm, pnpm, yarn, bun)
Directorio ~/.claude/ existe o puede crearse
Permisos de escritura en ~/.claude/

Instalación

ECC instalado (vía plugin O manualmente)
Si instalación manual: scripts en ~/.claude/scripts/hooks/
Si instalación manual: agentes en ~/.claude/agents/
Si instalación manual: comandos en ~/.claude/commands/
Rules instaladas para el/los lenguaje(s) del proyecto
Skills instaladas (mínimo search-first y tdd-workflow)
CLAUDE_PLUGIN_ROOT definido si es instalación manual

Configuración de hooks

~/.claude/settings.json existe y es JSON válido
Sección hooks.PreToolUse presente en settings.json
Sección hooks.PostToolUse presente en settings.json
Sección hooks.SessionStart presente en settings.json
Sección hooks.PreCompact presente en settings.json
ECC_HOOK_PROFILE definido (o usando default standard)
Script run-with-flags.js presente en scripts/hooks/

Configuración adicional

MCPs configurados si necesitás herramientas externas (GitHub, Brave Search, etc.)
API keys de MCPs en variables de entorno (no hardcodeadas en JSON)
Package manager configurado para el proyecto (si autodetección no funciona)
tmux instalado si querés usar el hook auto-dev-server
Aliases de Claude Code para diferentes contextos (opcional)

Verificación funcional

Claude Code inicia sin errores
Hook SessionStart se ejecuta al iniciar sesión
Comando /plan funciona en Claude Code
Agente spec-writer accesible en Claude Code
Rules visibles y cargadas en Claude Code
Hook block-no-verify bloquea git commit --no-verify
Quality gate se ejecuta después de editar archivos
Variables de entorno de ECC funcionan correctamente

Seguridad y mantenimiento

API keys no están en archivos commiteados a git
~/.claude/settings.json no está en ningún repositorio público
Entendés cómo actualizar ECC cuando haya nueva versión
Sabés cómo deshabilitar hooks si interfieren con un proyecto específico
Tenés backup de settings.json antes de modificarlo

Resumen del capítulo

En este capítulo instalaste Everything Claude Code de forma completa. Los conceptos clave son:

Dos opciones de instalación: Plugin (automático, actualizaciones fáciles) o Manual (control granular, auditable).
Estructura de directorios: ~/.claude/ para configuración global, .claude/ del proyecto para configuración local. La configuración del proyecto tiene precedencia.
Hooks son el motor de automatización: Se ejecutan en cuatro eventos — PreToolUse, PostToolUse, SessionStart, PreCompact. Los PreToolUse pueden bloquear operaciones si retornan exit code distinto de 0.
Hook Runtime Controls: Tres perfiles (minimal, standard, strict) y la variable ECC_DISABLED_HOOKS para ajustar sin editar archivos.
Package manager detection: Cascada de 4 métodos con variable de entorno como override de mayor prioridad.
MCPs extendiendo Claude Code: Herramientas adicionales como GitHub, búsqueda web, bases de datos, conectadas vía ~/.claude.json.

En el próximo capítulo veremos en detalle el sistema de agentes: cómo funcionan, cuándo usar cada uno, y cómo crear tus propios agentes personalizados.