El modo headless de Claude Code ejecuta el agente de forma no interactiva: le pasas el flag -p (o --print) con un prompt, Claude se ejecuta hasta el final, imprime el resultado y termina — sin REPL, sin teclado, sin nadie esperando frente a una terminal. Ese único flag convierte un asistente de programación interactivo en una herramienta de línea de comandos compatible con Unix a la que puedes canalizar datos, envolver en un script, programar con cron o integrar en un pipeline de CI/CD. Esta guía cubre cómo funciona el modo headless en 2026, los flags que realmente importan, cómo obtener JSON procesable de él, las trampas de permisos y autenticación que rompen silenciosamente las ejecuciones desatendidas, y las lecciones de ejecutar un pipeline headless de Claude Code en producción.
¿Qué es el modo headless de Claude Code?
El modo headless es Claude Code ejecutándose sin su interfaz de terminal interactiva. Añade -p (abreviatura de --print) a cualquier comando claude y, en lugar de abrir el REPL, Claude lee el prompt, ejecuta el ciclo completo del agente (leyendo archivos, ejecutando herramientas, editando código), luego imprime el resultado final y termina con un código de estado. Es el mismo agente que impulsa Claude Code interactivo, solo que dirigido por un script en lugar de por una persona. A partir de 2026 la función vive bajo el Agent SDK, que también se distribuye como paquetes de Python y TypeScript si quieres callbacks y objetos de mensaje nativos en lugar de invocar el shell.
claude -p "What does the auth module do?"
Como el modo no interactivo lee desde stdin, se compone como cualquier otra herramienta de CLI. Puedes canalizar directamente un log de compilación y redirigir la respuesta hacia fuera:
cat build-error.txt | claude -p "concisely explain the root cause of this build error" > cause.txt
Esa capacidad de composición (stdin de entrada, texto o JSON de salida, un código de salida sobre el que puedes ramificar) es la razón misma de que exista el modo headless.
Cómo obtener una salida estructurada que puedas procesar
El texto plano está bien para una persona que lee un log, pero la automatización necesita estructura. El flag --output-format acepta exactamente tres valores: text (el predeterminado), json y stream-json. El formato json es el caballo de batalla: devuelve la respuesta más metadatos de sesión en un único objeto.
claude -p "Summarize this project" --output-format json | jq -r '.result'
La carga útil JSON incluye result (el texto), session_id, num_turns, is_error, duration_ms y, algo crucial para quien ejecute esto a escala, total_cost_usd, una cifra de coste por invocación para que puedas controlar el gasto sin abrir el panel. Para respuestas legibles por máquina que se ajusten a una forma que tú defines, combina --output-format json con --json-schema '{...}'; el objeto validado vuelve en un campo structured_output. Usa stream-json con --verbose cuando quieras renderizar los tokens a medida que llegan. Procesa cualquiera de estos con jq y tendrás una interfaz programática fiable.
Permisos: la parte que hace tropezar a todos
Una sesión interactiva pregunta antes de ejecutar un comando de shell o editar un archivo. Una ejecución headless no tiene a quién preguntar, así que por defecto rechazará la acción y puede bloquear tu pipeline. Tienes que conceder el permiso de antemano. La herramienta más limpia es --allowedTools, una lista blanca separada por comas:
claude -p "Run the test suite and fix any failures" --allowedTools "Bash,Read,Edit"
Para un control más fino, el flag utiliza la sintaxis de reglas de permisos, de modo que --allowedTools "Bash(git diff *)" permite solo comandos que empiezan por git diff. Para establecer una línea base para toda la ejecución en lugar de enumerar herramientas, pasa un --permission-mode: acceptEdits deja que Claude escriba archivos y ejecute comandos habituales del sistema de archivos sin preguntar, mientras que dontAsk deniega cualquier cosa no permitida explícitamente, que es la opción correcta para un trabajo de CI blindado. El instrumento más contundente, --dangerously-skip-permissions, aprueba todo y solo debería tocar un sandbox o contenedor desechable, nunca una máquina con credenciales o acceso a producción.
Autenticación: clave de API frente a token OAuth
Las ejecuciones headless necesitan credenciales que no impliquen un inicio de sesión en el navegador, y hay dos caminos honestos. El primero es ANTHROPIC_API_KEY, una clave de la Anthropic Console facturada por token, el ajuste natural para runners de CI y automatización de pago por uso. El segundo te permite reutilizar una suscripción existente: ejecuta claude setup-token una vez, completa el flujo OAuth en un navegador e imprimirá un token de un año que exportas como CLAUDE_CODE_OAUTH_TOKEN. Ese token está vinculado a un plan Pro, Max, Team o Enterprise y su alcance se limita únicamente a la inferencia. Elige según el modelo de facturación: uso de API medido para cargas de trabajo de CI puntuales, el token de suscripción para un agente estable siempre activo. Una advertencia para las llamadas con scripts: el modo --bare (que omite el autodescubrimiento de hooks, skills y servidores MCP para ejecuciones reproducibles) también omite OAuth, así que bajo --bare debes proporcionar ANTHROPIC_API_KEY.
Ejecutar Claude Code en CI/CD y en cron
Una vez que un solo comando funciona de forma no interactiva, programarlo es DevOps corriente. Una entrada de cron que ejecuta claude -p en un VPS convierte el agente en una tarea que se dispara por sí sola: clasificando logs a las 2 de la madrugada, redactando un changelog o corrigiendo el lint según un horario. En un pipeline, envuelve la llamada en un script que canalice un diff y ramifique según el código de salida; Anthropic ofrece integraciones nativas de GitHub Actions y GitLab CI/CD precisamente para esto. Dos flags importan para la fiabilidad desatendida. Añade --bare para que las ejecuciones no hereden silenciosamente los hooks o servidores MCP que casualmente estén en el ~/.claude de un compañero, y así obtengas el mismo resultado en cada máquina. Y usa --continue o --resume <session_id> cuando un trabajo necesita varios turnos que se construyen unos sobre otros, capturando el ID de sesión de la salida JSON de la primera llamada. Si estás montando la máquina tú mismo, nuestra guía sobre cómo autoalojar tus aplicaciones en un VPS cubre los fundamentos de cron y de fortalecimiento que mantienen sano a un agente programado.
| Flag | Qué hace | Cuándo lo necesitas |
|---|---|---|
-p / --print | Ejecuta de forma no interactiva, imprime el resultado, termina | Toda ejecución headless |
--output-format json | Resultado estructurado con coste + metadatos de sesión | Cualquier invocador con script |
--json-schema | Fuerza la salida a un esquema (structured_output) | Extracción legible por máquina |
--allowedTools | Preaprueba herramientas específicas | Evitar que la ejecución se bloquee ante los prompts |
--permission-mode | Línea base para toda la sesión (acceptEdits, dontAsk) | CI blindado |
--bare | Omite el autodescubrimiento para ejecuciones reproducibles | Llamadas de CI y del SDK |
--continue / --resume | Conversaciones de varios turnos entre llamadas | Trabajos con estado |
Lo que aprendimos ejecutando un motor de contenido headless
Nosotros mismos usamos Claude Code headless en producción: el pipeline que investiga, escribe y publica los artículos aquí en TechRiseUps se ejecuta como un trabajo claude -p programado en nuestra propia infraestructura de WaseerHost, dirigido por un skill personalizado en lugar de por una persona frente al teclado. Se sostuvieron algunas lecciones que la documentación solo insinúa.
Los permisos son la causa número uno de una ejecución "atascada": un trabajo que parece colgarse casi siempre es Claude esperando una aprobación que nunca llegará, así que preaprueba cada herramienta que la tarea realmente necesite y nada más. Lee total_cost_usd del JSON en cada invocación y regístralo; los agentes desatendidos no tienen un techo de coste natural, y la cifra por ejecución es la única forma barata de detectar una tarea que se descontroló. Haz cada ejecución idempotente, porque un trabajo de cron acabará disparándose dos veces o reanudándose a mitad de camino, y un agente que añade a ciegas hace un desastre. Y para trabajos de larga duración que se ramifican con subagentes en segundo plano, eleva el límite de descriptores de archivo del proceso, porque un agente headless que abre muchos archivos y sockets puede alcanzar silenciosamente el ulimit predeterminado y quedarse bloqueado sin ningún error evidente. Nada de esto es exótico; es la aburrida higiene operativa que separa una demo de un pipeline en el que confías para que se ejecute mientras duermes.
Preguntas frecuentes
¿Qué es el modo headless en Claude Code?
Es Claude Code ejecutándose de forma no interactiva mediante el flag -p / --print. Claude lee un prompt, ejecuta el ciclo completo del agente, imprime el resultado final y termina, sin terminal interactiva. Está pensado para scripts, pipes, trabajos de cron y CI/CD en lugar de para programar de forma manual.
¿Cómo ejecuto Claude Code en headless sin pagar por claves de API?
Genera un token respaldado por suscripción con claude setup-token y luego expórtalo como CLAUDE_CODE_OAUTH_TOKEN. Se autentica contra un plan Pro, Max, Team o Enterprise en lugar de una facturación de API medida. Ten en cuenta que el modo --bare omite OAuth y sigue requiriendo ANTHROPIC_API_KEY.
¿Cómo evito que Claude Code pida permiso en modo headless?
Preaprueba herramientas con --allowedTools "Bash,Read,Edit", o establece una línea base de sesión con --permission-mode acceptEdits (o dontAsk para CI blindado). Usa --dangerously-skip-permissions solo dentro de un sandbox desechable, nunca en una máquina con credenciales reales.
¿Puedo ejecutar Claude Code headless desde Python?
Sí. El modo headless es parte del Agent SDK, que se distribuye como paquetes de Python y TypeScript además de la CLI claude -p. Usa los paquetes del SDK cuando quieras callbacks de aprobación de herramientas, objetos de mensaje nativos y salidas estructuradas sin tener que procesar stdout.
¿Es el modo headless lo mismo que el Claude Agent SDK?
Son dos puertas de entrada al mismo motor. claude -p es la forma CLI del Agent SDK — las mismas herramientas, el mismo ciclo de agente y la misma gestión de contexto. Los paquetes del SDK de Python y TypeScript te dan un control programático más completo para integrar agentes en aplicaciones.
Fuentes
- Documentación de Claude Code — Ejecutar Claude Code de forma programática (headless): el flag
-p/--print,--output-format,--bare, permisos,--continue/--resumey los campos de resultado JSON. - Documentación de Claude Code — Autenticación:
claude setup-token,CLAUDE_CODE_OAUTH_TOKENy en qué se diferencian los tokens de suscripción deANTHROPIC_API_KEY. - Documentación de Claude Code — GitHub Actions: integración nativa de CI para ejecutar el agente en pipelines.
Waqas Ahmed Waseer
Waqas Ahmed Waseer es desarrollador y creador de automatizaciones con más de 8 años construyendo sistemas en producción que usan más de 100.000 personas. Crea SaaS multiinquilino a medida, automatización con IA (n8n, flujos LLM, bots de WhatsApp) e infraestructura de hosting (WHM/cPanel, CloudLinux), y es el creador de WaSphere, FlowMaticX y la marca de hosting WaseerHost. Más de 100 proyectos entregados para pymes, agencias y startups financiadas.
