Modo headless de Claude Code: -p, CI y la GitHub Action
Scripte Claude Code como una herramienta Unix: prompts de un disparo con claude -p, archivos por pipe, JSON parseable, sesiones que se reanudan por id, modo --bare para CI y la GitHub Action @claude construyendo features desde un issue — directo del walkthrough del propio Anthropic.
TL;DR
- claude -p "prompt" ejecuta un disparo e imprime el resultado — sin sesión interactiva. Se combina como cualquier herramienta Unix: entra por pipe, sale por pipe, se encadena en scripts y pasos de CI.
- --output-format json devuelve el resultado más session_id, costes y metadatos; stream-json emite eventos delimitados por saltos de línea para consumidores en tiempo real. Parsee con jq y construya encima.
- Headless arranca sin permisos de edición ni destructivos. Conceda justo lo necesario con --allowedTools "Bash(git diff *),Edit" — sintaxis de reglas de permisos, coincidencia por prefijo.
- La GitHub Action @claude es modo headless con interfaz: etiquete a @claude en un issue o PR y lee código, crea PRs y commits, responde preguntas y revisa código — sobre sus propios runners de GitHub.
Building headless automation with Claude Code | Code w/ Claude
Canal: Anthropic20:59
Headless mode — official documentation
Documentación oficial: code.claude.com/docs
Claude Code GitHub Action — official docs
Documentación oficial: code.claude.com/docs
Los flags, límites y comportamientos de esta página están verificados contra la documentación oficial de headless; la charla de arriba es el walkthrough del propio Anthropic y la fuente visual de las capturas.
Las capturas se atribuyen a sus creadores con enlaces profundos a los minutos exactos. No se usan tomas del ponente ni del público.
Ejecutar Claude Code en modo headless, paso a paso
Parte 1 — Bases del modo headless
- 1
Qué es el modo headless
El modo headless es Claude Code sin la interfaz interactiva: el mismo agente, pilotado por programa. Anthropic lo presenta como un bloque de construcción simple para aplicaciones agénticas — úselo como una herramienta Unix en scripts y pipelines, para automatización de CI, entornos remotos o como motor detrás de una interfaz de chat web.
El encuadre del propio Anthropic: el SDK es acceso programático a Claude Code en entornos headless.Ver en 2:10 - 2
Prompts de un disparo con claude -p
El flag -p (o --print) ejecuta un único prompt y sale: claude -p "Write me a function that calculates the Fibonacci sequence". Nada queda abierto — obtiene la salida por stdout y un código de salida que sus scripts pueden comprobar. Combínelo con --allowedTools para conceder acceso de escritura por adelantado.
Una pregunta de un disparo: claude -p genera la función de Fibonacci y sale — sin TUI ni continuación.Ver en 3:30 - 3
Inyectar archivos directamente en Claude
El stdin funciona como en cualquier herramienta CLI: cat app.log | claude -p "summarize the most common error logs". En la demo de Anthropic entran 2000 líneas de log y sale un resumen de errores en lenguaje llano — el mismo truco sirve para fallos de build, stack traces y exportaciones. El stdin por pipe tiene un tope de 10 MB.
cat más el símbolo pipe más claude -p: dos mil líneas de log se vuelven un diagnóstico de tres frases.Ver en 3:55 - 4
Decodificar salidas que odia leer
El mismo patrón convierte salidas hostiles en respuestas: ifconfig | claude -p "what interfaces do I have configured? don't include lo". Cualquier cosa que imprima un comando — estado de red, errores del compilador, planes de terraform — puede pasar por Claude para un resumen humano.
ifconfig pasado por claude -p: cada interfaz explicada, loopback excluida a petición.Ver en 4:15 - 5
Obtener JSON estructurado
Añada --output-format json y la respuesta se vuelve un objeto parseable: el texto del resultado, la session_id, la duración y total_cost_usd. Para consumidores en vivo, --output-format stream-json emite eventos delimitados por líneas a medida que ocurren — la última línea es el resultado final.
Modo JSON: un solo bloque con el resultado, un id de sesión para reanudar después y el coste de la ejecución.Ver en 4:35
Parte 2 — Scriptar como un ingeniero
- 6
Conceder herramientas con intención
Headless arranca sin permisos de edición ni destructivos. --allowedTools preaprueba lo que la tarea necesita, con sintaxis de reglas de permisos: --allowedTools "Bash(npm run build),Bash(npm test:*),Write". Las herramientas MCP se pueden poner en lista blanca igual — conceda el conjunto más estrecho que resuelva el trabajo.
El análisis profundo del SDK: permisos de herramientas, modos de salida estructurada y system prompts personalizados en una sola diapositiva.Ver en 11:00 - 7
Conservar el contexto entre ejecuciones
El modo JSON devuelve una session_id — pásela de vuelta con --resume "$session_id" para continuar el mismo estado de conversación desde otra ejecución u otro proceso. Así se construyen productos interactivos encima: el usuario dice algo, Claude responde y usted preserva la sesión para el siguiente turno.
- 8
Gestionar permisos sin un humano
Si no puede predecir qué herramientas necesitará Claude, --permission-prompt-tool delega las decisiones de aprobación en un servidor MCP en tiempo de ejecución — la herramienta pregunta a su servicio (o a su usuario, vía su app) si permitir cada acción, en lugar de que usted lo liste todo por adelantado.
- 9
Ir a --bare para CI
--bare se salta el autodescubrimiento de hooks, skills, comandos personalizados, subagentes, plugins, servidores MCP y CLAUDE.md para el arranque más rápido posible — recomendado para scripts y CI, y llamado a ser el valor por defecto de -p. Requiere ANTHROPIC_API_KEY y recibe el contexto explícitamente vía flags.
Parte 3 — La GitHub Action @claude
- 10
Conocer la GitHub Action @claude
La GitHub Action es modo headless con una interfaz construida sobre el SDK. Etiquete a @claude en cualquier PR o issue y puede leer su código, crear PRs, añadir commits a los existentes, responder preguntas y revisar cambios — ejecutándose en sus runners de GitHub de siempre, así que no hay infraestructura que cuidar.
El contrato de la Action: etiquete a @claude, describa lo que necesita y trabaja el repositorio en sus propios runners.Ver en 17:10 - 11
Asignar un issue a Claude
En la demo en directo de Anthropic, un comentario de «@claude please implement this feature and comment on it» hizo que el bot respondiera con un plan acotado — puntos de lo que iba a construir — antes de crear la rama, los commits y el pull request, todo trazable en los logs de la Action.
El comentario @claude en un issue real: Claude responde con un plan acotado antes de tocar código.Ver en 7:50 - 12
Instalarla en su repositorio
El resultado es un resumen de implementación con casillas marcadas en el issue — features añadidas, todos cerrados. Para llegar ahí, abra Claude Code en su repositorio y ejecute /install-github-action: un flujo interactivo abre un PR con el YAML del workflow; luego configure las claves de API como secrets del repo y haga merge.
La ejecución terminada: un resumen de implementación con cada feature que la Action añadió a la app de demo.Ver en 13:30
Headless vs interactivo vs SDK vs la GitHub Action
Cuatro maneras de pilotar el mismo agente — elija según quién (o qué) pregunta:
- 1CLI interactiva — la sesión TUI: prompts de permiso, modo plan, /commands. Para humanos que pilotan una tarea ahora mismo.
- 2Headless con claude -p — un disparo programático: stdin y stdout, códigos de salida, sin interfaz. Para scripts, tareas de cron y preguntas rápidas desde otras herramientas.
- 3El Agent SDK — la misma potencia headless como librería tipada: sesiones multipaso, herramientas propias, streaming. Cuando Claude es un componente dentro de su aplicación.
- 4La GitHub Action @claude — headless sobre el modelo de eventos de GitHub: issues, PRs y reviews en sus propios runners. Para automatización acotada al repo que todo el equipo puede disparar.
- 5--bare headless — un arranque despojado para CI: sin CLAUDE.md, hooks, skills, plugins ni autodescubrimiento de MCP, contexto explícito vía flags, el arranque en frío más rápido.
Comparten el mismo acceso al modelo y el mismo sistema de permisos — una regla de permiso concedida a headless aplica en todas partes, por eso importa la disciplina con --allowedTools.
¿El modo headless se porta mal? Primeros auxilios
Cinco tropiezos propios del modo headless, y el arreglo de cada uno:
- 1El script termina antes de que Claude acabe. Compruebe el código de salida: 0 es éxito, cualquier otra cosa falló. SIGTERM sale con 143 y deja el turno a medias — termine las ejecuciones con SIGINT o con interrupt() del SDK si debe parar a mitad de turno.
- 2La entrada por pipe se truncó en silencio. El stdin tiene un tope de 10 MB — escriba los payloads grandes a un archivo y referencie la ruta en el prompt.
- 3«--bg rejected» o un error de --cloud. Los flags de solo interactivo no aplican a -p: --bg se rechaza sin más, y --cloud necesita un id de sesión para encolar un mensaje, no una descripción de tarea.
- 4La ejecución de CI ignora su CLAUDE.md y sus hooks. Es --bare haciendo su trabajo: se salta el autodescubrimiento. Pase el contexto explícitamente con --settings, --mcp-config, --agents o --plugin-dir.
- 5Las tareas bash en segundo plano mueren a mitad de ejecución. Los shells en segundo plano se matan unos 5 segundos después de llegar el resultado; los subagentes y workflows mantienen el proceso vivo hasta un tope de inactividad de 10 minutos. Espérelos explícitamente en CI.
Para todo lo demás, añada --verbose y lea los eventos stream-json — system/init nombra el modelo, las herramientas y los servidores MCP que se cargaron de verdad.