Modo headless en Claude Code: claude -p y automatización
El modo headless ejecuta Claude Code sin interfaz conversacional: pasas el prompt como argumento con claude -p "..." y obtienes solo el resultado final en stdout. Eso te deja invocar Claude Code como cualquier proceso del sistema, dentro de scripts y pipelines, conservando el loop agéntico completo (herramientas, subagentes, skills, búsqueda).
La clave que lo distingue de la API: en modo headless, el loop agéntico sigue activo. Claude Code puede leer archivos, correr comandos, invocar MCP y activar skills antes de devolver el resultado. Si ya construiste un workflow en Claude Code, funciona igual en headless, sin reescribir nada.
Qué es y cómo funciona
La sesión normal de Claude Code es interactiva: tú escribes, el modelo responde, tú ajustas. Ese ciclo es secuencial y manual, y no escala: si necesitas procesar cien archivos, hacerlo turno a turno no es opción.
El modo headless rompe ese límite. El flag es --print, abreviado -p:
claude -p "Resume los cambios del último commit en 3 bullets."
Claude Code procesa la instrucción, ejecuta el loop agéntico internamente y devuelve la respuesta final en stdout. Sin interfaz, sin turnos visibles, sin spinner. Solo el output.
La analogía: es la diferencia entre abrir una calculadora con pantalla y llamar a python3 -c "print(2+2)". El resultado es el mismo; el modo de invocación cambia lo que puedes hacer con él.
Pipear entrada y salida
El modo headless brilla combinado con el shell. Puedes pasarle la salida de otro comando:
cat error.log | claude -p "¿Qué está fallando aquí?"
git diff | claude -p "Revisa estos cambios y señala riesgos."
Y para que un script procese la respuesta sin parsing frágil, Claude Code puede devolver JSON estructurado en lugar de texto libre.
Para qué sirve
- Procesar en lote: analizar muchos archivos, reportes o documentos sin hacerlo a mano uno por uno.
- Integrar en pipelines: meter a Claude Code en un script de CI, un cron o un flujo de datos.
- Escalar workflows existentes: si ya tienes skills y subagentes construidos, headless los reutiliza sin reescribir la lógica.
Para tareas recurrentes en el tiempo, se combina con /loop y con hooks.
Preguntas frecuentes
¿Qué es el modo headless en Claude Code?
Es la forma de ejecutar Claude Code sin la interfaz conversacional: pasas el prompt como argumento con claude -p "..." y obtienes solo el resultado final en stdout. Sirve para usarlo dentro de scripts, pipelines y procesos automatizados.
¿Qué hace el flag -p en Claude Code?
-p (abreviatura de --print) ejecuta Claude Code en modo headless: procesa el prompt que le pasas, corre el loop agéntico internamente y devuelve la respuesta final sin abrir una sesión interactiva.
¿El modo headless conserva las herramientas y skills?
Sí. A diferencia de llamar a la API directamente, el modo headless mantiene el loop agéntico completo: leer archivos, correr comandos, invocar MCP, activar skills y subagentes. Lo que funciona en la sesión interactiva funciona en headless.
¿Cómo le paso la salida de otro comando a Claude Code?
Con un pipe del shell: por ejemplo cat error.log | claude -p "¿qué falla?" o git diff | claude -p "revisa estos cambios". Para procesar la respuesta en un script, Claude Code puede devolver JSON estructurado.
Recursos relacionados
- Hooks en Claude Code: automatizar acciones en eventos del ciclo de vida.
- /loop: tareas recurrentes.
- Guía completa para dominar Claude Code.
Tu siguiente paso
Los comandos de automatización y decenas más están en la Cheat Sheet de Claude Code: una hoja imprimible, en español.
Descargar la Cheat Sheet gratis
Es el resumen de Ship with Claude Code, la guía de Takren (14 módulos, 190 capítulos, actualizaciones gratuitas).