🌱 Empieza aquí · Aviso de salida grande en el contexto

Esta semilla le pone a tu asistente un vigilante de tamaño. Cada vez que una herramienta le devuelve un resultado enorme (un archivo leído completo, un comando que escupe miles de líneas), el vigilante le deja una nota: "esto entró grande; la próxima vez acótalo". Nunca bloquea nada, solo avisa.

Para instalarla

Abre esta carpeta con Claude Code y dile a tu asistente:

"Siembra esta semilla 🌱"

Con eso basta de tu parte. Tu asistente hace todo lo técnico y al final te dice cómo comprobar que quedó funcionando. Vas a ver algunas palabras en inglés en la pantalla; ni caso, él te guía.

¿Otras formas de pedírselo? "instala esta semilla", "pon a funcionar el aviso de salida grande", "haz el setup de esto". Te entiende igual.

Para el asistente que siembra 🤖

Instala este hook (gancho de automatización) del evento PostToolUse (después de usar una herramienta). Es un script de Python 3 que lee el evento por entrada estándar, mide el texto de tool_response y, si pasa del umbral, imprime un JSON con hookSpecificOutput.additionalContext. Siempre sale con código 0. Usa $HOME siempre y no inventes rutas. Corre los comandos desde la carpeta de esta semilla.

1. Copia el kernel

Claude Code (macOS o Linux):

mkdir -p "$HOME/.claude/hooks"
cp kernel/salida-acotada.py "$HOME/.claude/hooks/salida-acotada.py"
cp kernel/probar-salida-acotada.sh "$HOME/.claude/hooks/probar-salida-acotada.sh"
chmod +x "$HOME/.claude/hooks/salida-acotada.py" "$HOME/.claude/hooks/probar-salida-acotada.sh"

Windows (Git Bash o WSL): los mismos comandos funcionan en Git Bash o WSL. Requiere python3 en el PATH. Si la persona usa Claude Code nativo en Windows sin python3, avísale que este hook necesita Python 3. Esta combinación no se probó.

2. Registra el hook en `settings.json`

Abre $HOME/.claude/settings.json (créalo si no existe) y agrega esta entrada dentro de hooks.PostToolUse. Si ya hay hooks de PostToolUse, suma este objeto al arreglo existente en lugar de reemplazarlo. Respeta el JSON válido (comas, llaves).

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash|Read|Grep|Glob|WebFetch|mcp__.*",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$HOME/.claude/hooks/salida-acotada.py\""
          }
        ]
      }
    ]
  }
}

El matcher limita el hook a las herramientas que suelen traer salidas grandes: comandos (Bash), lectura de archivos (Read), búsquedas (Grep, Glob), páginas web (WebFetch) y cualquier herramienta de un servidor MCP (mcp__.*), que es donde llegan las capturas de pantalla. Puedes agregar más nombres separados por |.

3. (Opcional) Ajusta los umbrales

Solo si la persona lo pide. Estas variables de entorno deben existir en el entorno donde corre Claude Code (por ejemplo en el bloque "env" de settings.json):

SALIDA_ACOTADA_UMBRAL_CHARS — caracteres de texto para avisar (por defecto 20000).
SALIDA_ACOTADA_UMBRAL_IMAGENES — capturas en un mismo resultado para avisar (por defecto 4).

El valor va entre comillas y es un número entero sin espacios ni letras ("30000", no "30 000" ni "30k"). Si no es un entero, el hook usa el valor por defecto.

{
  "env": {
    "SALIDA_ACOTADA_UMBRAL_CHARS": "30000"
  }
}

4. Verificación post-siembra (obligatoria)

a) Los archivos quedaron colocados:

ls -la "$HOME/.claude/hooks/salida-acotada.py" "$HOME/.claude/hooks/probar-salida-acotada.sh"; echo "exit=$?"

Salida esperada: dos líneas que listan los archivos (con x en los permisos) y exit=0. Si sale No such file or directory, repite el paso 1.

b) El hook avisa cuando debe (prueba de comportamiento, simula un resultado de 60 000 caracteres):

HOOK_PY="$HOME/.claude/hooks/salida-acotada.py"
GRANDE=$(python3 -c "print('x'*60000)")
printf '%s' "{\"tool_name\":\"Bash\",\"tool_input\":{\"command\":\"cat enorme.log\"},\"tool_response\":{\"stdout\":\"$GRANDE\"}}" | python3 "$HOOK_PY"; echo "EXIT=$?"

Salida esperada: una línea JSON con "additionalContext" que empieza con Salida grande: 58 KB de texto de Bash entraron al contexto (cat enorme.log), y EXIT=0.

c) El hook calla cuando debe (prueba señuelo, un resultado chico):

HOOK_PY="$HOME/.claude/hooks/salida-acotada.py"
printf '%s' '{"tool_name":"Read","tool_input":{"file_path":"/x.md"},"tool_response":"hola"}' | python3 "$HOOK_PY"; echo "EXIT=$?"

Salida esperada: sin ninguna salida y EXIT=0.

d) El banco completo de señuelos:

bash "$HOME/.claude/hooks/probar-salida-acotada.sh"; echo "EXIT=$?"

Salida esperada: siete líneas OK, resultado: 7/7 y EXIT=0. Para confirmar que el banco sí distingue, córrelo contra un hook mudo: debe reprobar.

HOOK=true bash "$HOME/.claude/hooks/probar-salida-acotada.sh"; echo "EXIT=$?"

Salida esperada: cuatro líneas MAL ... debía avisar y calló, resultado: 3/7 y EXIT=1.

e) El hook quedó registrado:

grep -q 'salida-acotada.py' "$HOME/.claude/settings.json" && echo 'REGISTRADO'

Salida esperada: REGISTRADO. El hook empieza a correr en la siguiente sesión de Claude Code (o después de revisar la configuración con /hooks).

Cuando todo dé lo esperado, avísale a la persona en una línea qué gana con esto.

✅ ¿Cómo sé que funcionó?

Casi nunca lo vas a ver, y eso está bien: el aviso no es para ti, es para tu asistente. Mientras los resultados sean de tamaño razonable, el hook calla. Cuando una herramienta mete un resultado enorme, tu asistente recibe la nota y, a partir de ahí, debería leer por partes (las primeras líneas, un rango, un conteo) o encargarle la lectura a un subagente, en lugar de cargar todo de golpe otra vez. Si quieres comprobarlo, pídele que lea completo un archivo muy grande y pregúntale después si recibió algún aviso. 🌱