Piping y stdin

Fundamentos del piping

El piping es un mecanismo estándar de los sistemas Unix y de las terminales modernas de Windows que permite encadenar la salida de un programa con la entrada de otro usando el operador |. Claude Code aprovecha este mecanismo para recibir contenido externo a través de la entrada estándar (stdin) y procesarlo con la capacidad de razonamiento del modelo.

La estructura básica es siempre la misma: un comando que genera contenido, el operador pipe | y Claude Code en modo print (-p) con una instrucción que indica qué hacer con ese contenido:

comando-que-genera-contenido | claude -p "instrucción sobre qué hacer"

Claude recibe el contenido canalizado como parte del contexto de la conversación y lo procesa según la instrucción proporcionada. Por ejemplo, para analizar el contenido de un archivo:

cat src/auth/session.ts | claude -p "explica qué hace este código"

O para obtener un resumen de los logs de una aplicación:

cat /var/log/app/error.log | claude -p "resume los errores más frecuentes"

El piping con | y el flag -p convierte a Claude Code en un procesador de texto inteligente que se integra con cualquier herramienta de terminal. El contenido canalizado se incorpora al contexto del agente y se procesa según la instrucción proporcionada.

Es importante utilizar el flag -p (modo print) al trabajar con pipes, ya que este modo está diseñado para recibir entrada, producir salida y terminar el proceso. El modo interactivo no está preparado para recibir contenido por stdin de la misma manera.

Análisis de código y archivos

Uno de los usos más directos del piping es enviar archivos de código para su análisis. A diferencia de abrir una sesión interactiva donde Claude busca y lee archivos por su cuenta, el piping permite seleccionar exactamente qué contenido enviar y formular preguntas concretas.

Para analizar un archivo completo:

cat package.json | claude -p "lista las dependencias de producción y desarrollo por separado"

Para enviar solo una parte de un archivo usando head, tail o rangos de líneas con sed:

sed -n '50,100p' src/database/connection.ts | claude -p "revisa esta función de conexión"

Para combinar varios archivos en una sola entrada:

cat src/models/user.ts src/models/product.ts | claude -p "compara estos dos modelos y sugiere una interfaz base común"

Análisis de diferencias de código

Un caso de uso especialmente valioso es el análisis de diffs de Git. La salida de git diff contiene toda la información sobre los cambios realizados, y Claude puede interpretarla para generar resúmenes, detectar problemas o crear mensajes de commit:

git diff | claude -p "genera un mensaje de commit descriptivo para estos cambios"

git diff main..feature/auth | claude -p "resume los cambios de esta rama respecto a main"

git log --oneline -20 | claude -p "agrupa estos commits por funcionalidad"

Procesamiento de logs y errores

El piping resulta especialmente eficaz para procesar logs de aplicación, trazas de error y salidas de herramientas de diagnóstico. Claude puede identificar patrones, clasificar errores y sugerir soluciones a partir del contenido recibido.

Para analizar la salida de un test que ha fallado:

npm test 2>&1 | claude -p "identifica las causas de los fallos y sugiere correcciones"

El operador 2>&1 redirige la salida de error estándar (stderr) a la salida estándar (stdout), asegurando que Claude reciba tanto los mensajes de error como la salida normal del proceso.

Para filtrar y analizar logs específicos:

grep "ERROR" /var/log/app/application.log | claude -p "clasifica estos errores por tipo y frecuencia"

Para procesar la salida de herramientas de diagnóstico del sistema:

docker logs mi-contenedor --tail 100 | claude -p "detecta posibles problemas en estos logs"

El piping de logs y salidas de error a Claude Code permite obtener análisis inteligentes de problemas que de otro modo requerirían lectura manual. Claude puede clasificar errores, detectar patrones recurrentes y sugerir acciones correctivas.

Pipelines de múltiples etapas

La capacidad de componer cadenas de pipes permite construir pipelines donde cada paso transforma o filtra la información antes de que llegue a Claude.

Un pipeline típico podría filtrar primero los datos relevantes y enviar solo esa selección al agente:

find src -name "*.ts" -newer tsconfig.json | xargs cat | claude -p "revisa los archivos TypeScript modificados recientemente"

Otro ejemplo con procesamiento intermedio:

git diff --name-only HEAD~5 | grep "\.py$" | xargs cat | claude -p "resume los cambios en archivos Python de los últimos 5 commits"

Este pipeline:

• 1. Lista los archivos modificados en los últimos 5 commits.
• 2. Filtra solo los archivos Python.
• 3. Concatena su contenido.
• 4. Envía todo a Claude para su análisis.

Encadenar la salida de Claude

La salida de Claude Code en modo print también se puede canalizar a otros programas, completando el pipeline:

claude -p "genera un script bash que limpie archivos temporales del proyecto" > cleanup.sh

git diff | claude -p --output-format json "clasifica cada cambio por tipo" | jq '.result'

El flag --output-format json resulta clave para este tipo de encadenamiento, ya que produce una salida estructurada que herramientas como jq pueden procesar.

Entrada con heredoc

Los heredoc (here documents) permiten enviar bloques de texto multilínea directamente a Claude Code sin necesidad de un archivo intermedio. Son útiles para proporcionar contenido junto con instrucciones detalladas.

En Bash:

claude -p << 'EOF'
Analiza el siguiente error de producción y sugiere una solución:

TypeError: Cannot read properties of undefined (reading 'map')
    at UserList.render (src/components/UserList.tsx:42:18)
    at renderWithHooks (node_modules/react-dom/...)
    at mountIndeterminateComponent (node_modules/react-dom/...)
EOF

En PowerShell, el equivalente usa la sintaxis de string multilínea:

@"
Analiza el siguiente error de producción y sugiere una solución:

TypeError: Cannot read properties of undefined (reading 'map')
    at UserList.render (src/components/UserList.tsx:42:18)
"@ | claude -p "analiza este error"

Los heredoc son particularmente prácticos para enviar trazas de error, fragmentos de configuración o descripciones de problemas que contienen varias líneas y caracteres especiales que complicarían el uso de comillas.

Casos de uso prácticos

Generación de documentación

Canalizar código fuente para generar documentación técnica:

cat src/api/routes/*.ts | claude -p "genera documentación OpenAPI en YAML para estos endpoints"

Revisión de seguridad

Enviar la configuración del proyecto para un análisis de seguridad:

cat docker-compose.yml .env.example | claude -p "identifica riesgos de seguridad en esta configuración"

Transformación de datos

Convertir datos entre formatos aprovechando la capacidad de comprensión del agente:

cat datos.csv | claude -p "convierte este CSV a JSON, agrupando por el campo 'departamento'"

Análisis de dependencias

Evaluar el estado de las dependencias de un proyecto:

npm outdated 2>&1 | claude -p "prioriza qué dependencias actualizar primero y por qué"

flowchart LR
    A["Comando de terminal"] -->|pipe| B["claude -p 'instrucción'"]
    B -->|stdout| C["Resultado"]
    C -->|pipe| D["Otro programa o archivo"]

El piping transforma a Claude Code de un agente interactivo a un componente de pipeline que se integra con el ecosistema completo de herramientas de terminal, ampliando sus capacidades sin necesidad de plugins ni configuraciones adicionales.