≡En resumen
- claude -p ejecuta una tarea sin interfaz y devuelve el resultado por la salida estándar.
- Con --output-format json o stream-json obtienes resultados que un script puede procesar.
- --allowedTools y --permission-mode definen qué puede hacer Claude sin pedir permiso.
- --bare arranca sin hooks, skills, MCP ni CLAUDE.md locales: es lo recomendable en CI.
- Sin --bare, un claude -p ejecuta los hooks y servidores MCP del proyecto aunque no hayas confiado en esa carpeta.
01 ¿Qué es el modo headless de Claude Code?
Normalmente usas Claude Code en una sesión interactiva: escribes, Claude responde, te pide permisos y sigues conversando. El modo headless (sin interfaz) elimina esa conversación: lanzas un comando con la tarea, Claude trabaja con sus herramientas y, al terminar, imprime el resultado y sale con un código de estado, 0 si todo fue bien y distinto de 0 si falló.
La documentación oficial lo presenta hoy como el uso del Agent SDK desde la línea de comandos: el mismo bucle de agente, las mismas herramientas y la misma gestión de contexto que Claude Code, pero listo para scripts y automatizaciones. Si necesitas más control, el SDK también existe como paquete de Python y TypeScript.
02 Opciones principales de claude -p
| Opción | Para qué sirve |
|---|---|
| -p, --print | Ejecuta la tarea en modo no interactivo |
| --output-format | text (por defecto), json con resultado y metadatos, o stream-json con eventos en tiempo real |
| --json-schema | Fuerza una salida que cumpla un esquema; llega en el campo structured_output |
| --allowedTools | Herramientas que Claude puede usar sin pedir permiso, como "Read,Edit,Bash" |
| --permission-mode | Modo base de permisos: acceptEdits, dontAsk o auto |
| --permission-prompts none | Deniega lo que pediría aprobación, para ejecuciones sin nadie delante |
| --bare | Arranca sin cargar hooks, skills, plugins, MCP, memoria ni CLAUDE.md |
| --append-system-prompt | Añade instrucciones al prompt de sistema por defecto |
| --continue / --resume | Continúa la última conversación o una concreta por su identificador |
| --max-turns / --max-budget-usd | Limitan los turnos o el gasto estimado de la ejecución |
Con --output-format json la respuesta incluye el texto en el campo result, el identificador de sesión y una estimación de coste, todo en JSON fácil de procesar con herramientas como jq.
03 Modo --bare y seguridad en ejecuciones automáticas
Sin más opciones, claude -p carga el mismo contexto que una sesión interactiva: tu CLAUDE.md, tus skills, tus plugins, la memoria automática y los servidores MCP configurados en la carpeta o en ~/.claude. Eso hace que el resultado dependa de la máquina en la que se ejecute.
Qué hace --bare
Omite el descubrimiento automático de hooks, skills, comandos, subagentes, plugins, servidores MCP, memoria y CLAUDE.md. Claude solo tiene Bash y las herramientas de lectura y edición de archivos.
Cómo añadir lo que necesitas
Pasa el contexto de forma explícita: --append-system-prompt, --settings, --mcp-config, --agents o --plugin-dir.
Autenticación
En modo bare no se leen las credenciales de tu sesión ni del llavero: define ANTHROPIC_API_KEY o usa las credenciales de tu proveedor en la nube.
Futuro por defecto
La documentación indica que --bare es el modo recomendado para scripts y SDK y que será el predeterminado de -p en una versión futura.
04 Permisos en ejecuciones desatendidas
En modo headless nadie responde a las peticiones de permiso, así que tienes que decidir antes qué puede hacer Claude.
-
1
Lista herramientas concretas
Con --allowedTools y la sintaxis de reglas, por ejemplo "Bash(git diff *),Bash(git commit *)", autorizas solo esos comandos.
-
2
Elige un modo base
dontAsk deniega todo lo que pediría permiso (útil en CI cerrada); acceptEdits permite editar archivos; auto deja que un clasificador revise cada acción.
-
3
Evita esperas
--permission-prompts none hace que lo que requeriría aprobación se deniegue y Claude no lo reintente.
-
4
Revisa las denegaciones
Con stream-json, cada denegación aparece como un evento y el resultado final las lista en permission_denials.
05 Ejemplos de uso del modo headless
Un script recibe el número de un pull request, obtiene el diff con la CLI de GitHub y se lo pasa a Claude: gh pr diff "$1" | claude -p --append-system-prompt "Eres un ingeniero de seguridad. Revisa vulnerabilidades." --output-format json. El resultado sale en JSON y otro paso del pipeline puede publicarlo como comentario.
Linter con IA
Un script de package.json pasa git diff main a claude -p para detectar erratas o incoherencias y devolverlas en formato archivo:línea.
Extracción de datos
Con --json-schema obtienes, por ejemplo, la lista de funciones de un archivo como un array que tu código consume directamente.
Commits automáticos
Claude revisa los cambios preparados y crea el commit, con permisos limitados a los comandos de git necesarios.
Conversaciones en varios pasos
Guardas el session_id de la primera ejecución y continúas con --resume en las siguientes.
06 Modo headless frente al Agent SDK, GitHub Actions y las rutinas
| Opción | Ideal para | Dónde se ejecuta |
|---|---|---|
| claude -p (headless) | Scripts, hooks de git y pipelines de cualquier sistema de CI | Donde lances el comando |
| Agent SDK en Python o TypeScript | Aplicaciones propias con callbacks de permisos y objetos de mensaje nativos | Tu aplicación |
| GitHub Actions | Responder a @claude y automatizar sobre eventos del repositorio | Runners de GitHub |
| Rutinas | Tareas periódicas o por API sin infraestructura propia | Nube de Anthropic |
La acción oficial para GitHub está construida sobre el mismo SDK: si tu código vive en GitHub, mira Claude Code GitHub Actions. Para tareas recurrentes sin servidores, las rutinas de Claude; y para repetir algo dentro de una sesión abierta, el comando /loop.
07 Buenas prácticas para usar claude -p en producción
- ✓Usa --bare en CI para que el resultado no dependa de la configuración de cada máquina.
- ✓Autoriza solo las herramientas y comandos que la tarea necesita.
- ✓Pide salida en JSON y valida el resultado antes de usarlo en el siguiente paso.
- ✓Limita turnos o presupuesto para evitar ejecuciones desbocadas.
- ✓Guarda la clave de API como secreto del sistema de CI, nunca en el repositorio.
- ✓Comprueba el código de salida del proceso para detectar fallos.
- ✓Para entradas grandes, escribe un archivo y referencia su ruta: la entrada por tubería tiene un límite de 10 MB.
Integrar agentes de IA en pipelines es cada vez más habitual en el desarrollo de software SaaS y en cualquier proyecto de desarrollo web a medida. Si quieres ver herramientas de la comunidad que se apoyan en el modo headless, consulta nuestro directorio de recursos para Claude.
Preguntas frecuentes sobre Modo headless de Claude Code (claude -p)
Es su modo no interactivo: con claude -p le pasas una tarea, Claude la ejecuta sin interfaz ni preguntas y devuelve el resultado por la salida estándar, listo para scripts y CI/CD.
Es la forma corta de --print. Ejecuta el prompt en modo no interactivo e imprime la respuesta al terminar, en lugar de abrir una sesión.
Añade --output-format json. El texto llega en el campo result junto al identificador de sesión y los metadatos. Para un formato concreto, combina esa opción con --json-schema.
Autoriza herramientas con --allowedTools o fija un modo con --permission-mode, por ejemplo dontAsk o acceptEdits. Con --permission-prompts none se deniega lo que requeriría aprobación.
Arranca Claude Code sin cargar hooks, skills, plugins, servidores MCP, memoria ni CLAUDE.md locales. Hace las ejecuciones más rápidas y reproducibles y evita ejecutar configuración de repositorios ajenos.
Sin --bare, claude -p usa el mismo inicio de sesión que tu Claude Code. En modo bare necesitas una clave de API en ANTHROPIC_API_KEY o las credenciales de tu proveedor en la nube.
Fuentes consultadas
Sobre el autor
Germán Gutiérrez
Development Manager en appyweb
Dirige el equipo de desarrollo de appyweb: aplicaciones web y móviles, SaaS, integraciones y arquitectura de software.
Ver perfil en LinkedIn ↗