Modo headless: ejecutar agentes sin interacción

En modo headless o non-interactive, un agente de IA se ejecuta sin ventana de chat — ideal para scripts y CI, pero sin poder preguntarte nada.

Qué significa headless

Normalmente chateas en vivo con un agente: te pregunta, respondes, sigue adelante. En modo headless o non-interactive, ese diálogo desaparece. Le pasas un prompt como argumento o mediante una tubería (pipe), el agente lo procesa y al final devuelve una respuesta única — sin preguntas intermedias, sin ventana de chat.

Cómo se ve esto en Claude Code

El comando claude -p "Encuentra el bug en auth.py" inicia Claude Code de forma no interactiva. También puedes pasar datos mediante pipe: cat error.log | claude -p "Explica la causa". La salida se puede obtener como texto plano o como JSON estructurado (--output-format json), lo que encaja bien en scripts.

Para qué se usa

Procesamiento por lotes (batch): recorrer automáticamente muchos archivos o tickets
CI/CD: p. ej. revisar automáticamente cada pull request en busca de erratas o problemas de seguridad
Cron jobs y automatizaciones programadas sin intervención humana

El riesgo: sin preguntas de seguimiento

La mayor diferencia con el modo interactivo: el agente no puede pedirte permiso o aclaración. Si se topa con una situación en la que normalmente preguntaría, tiene que decidir por sí mismo o abortar. Por eso la elección del modo de permisos (ver entrada propia) es especialmente importante en el uso headless: sin reglas claras, un agente puede hacer demasiado poco (aborta constantemente) o demasiado (ejecuta acciones arriesgadas sin preguntar).

EJEMPLO

# Script de CI: comprobación de erratas para cada diff de PR git diff main | claude -p "Encuentra erratas en este diff. Para cada hallazgo indica 'archivo:línea' y el error, nada más." --output-format json

🛠️ EJERCICIO — PRUÉBALO TÚ

Construye una llamada headless sencilla que resuma un archivo y observa cómo se comporta sin poder hacer preguntas.

Ejecuta en una terminal: claude -p "Resume este archivo en 3 frases" --allowedTools "Read" con un archivo real de tu proyecto.
Repite la llamada, pero indica un archivo que no exista — observa cómo reacciona el agente sin preguntar (error en lugar de pregunta).
Prueba --output-format json y mira el JSON resultante: ¿qué campos aparte del propio texto contiene?

✅ AUTOEVALUACIÓN

☐ ¿Pudiste explicar por qué el agente no simplemente preguntó al faltar el archivo?
☐ ¿Entendiste para qué sirve --allowedTools en este contexto?
☐ ¿Sabes en qué dos escenarios (batch, CI) el funcionamiento headless de la entrada tiene más sentido?

QUIZ RÁPIDO

¿Cuál es el mayor riesgo al ejecutar un agente en modo headless / non-interactive?