Inicio / Gestos cotidianos

Modo headless, estilos de salida y tareas en segundo plano

El modo headless ejecuta Claude Code sin interfaz interactiva con -p, --output-format determina si la salida sigue siendo texto o se convierte en un objeto JSON utilizable por un script, con el costo total incluido, y run_in_background deja que un comando largo continúe sin bloquear la conversación.

El modo headless ejecuta Claude Code sin interfaz interactiva, en un solo comando que devuelve su resultado y se detiene. El indicador -p (o --print) activa este modo, con un prompt dado como argumento.

claude -p "Resume los archivos modificados en este repositorio" --output-format json

Tres formatos de salida para tres usos

El parámetro --output-format acepta tres valores. text, el valor predeterminado, devuelve una respuesta en lenguaje natural destinada a un humano. json devuelve un único objeto estructurado, con el resultado, el identificador de sesión y el costo total en dólares junto con un desglose por modelo, una forma que un script puede leer sin analizar texto libre. stream-json devuelve la misma información en JSON Lines, un objeto por línea, útil cuando un programa quiere reaccionar antes de que termine por completo la ejecución. Un indicador --bare se salta el descubrimiento automático de hooks, skills, comandos personalizados, subagentes, plugins, servidores MCP, memoria automática y archivos CLAUDE.md al arrancar, lo que acelera el inicio. La documentación oficial lo recomienda para las llamadas con script y señala que podría convertirse en el valor predeterminado de -p en una versión futura. Esta ganancia de velocidad tiene una contrapartida que nada indica en pantalla: el modo bare nunca lee los identificadores OAuth ni el llavero del sistema, por lo que no se apoya en la conexión por suscripción, y un script que lo use debe fijar la variable ANTHROPIC_API_KEY en su entorno para autenticarse ante la API de Anthropic.

Dejar que un comando largo se ejecute sin bloquear

Un comando largo lanzado por la herramienta Bash de Claude Code puede pedir run_in_background: true en lugar de esperar a que termine. La herramienta devuelve entonces de inmediato un identificador de tarea, el comando continúa en segundo plano, y su salida se vuelve a leer después con la herramienta Read. El atajo Ctrl+B mientras un comando se ejecuta hace el mismo cambio a mano, y el comando /tasks enumera y detiene las tareas en curso.

Este cambio también ocurre solo: un comando que llega a su plazo de expiración sin haber terminado pasa automáticamente a tarea en segundo plano en lugar de cortarse en seco, salvo para tres familias de comandos que siguen siendo bloqueantes hasta el final, los que empiezan por sleep, los que contienen git, y los comandos demasiado compuestos para ser analizados por el mecanismo de seguridad. El identificador de sesión que --output-format json devuelve es el mismo que retoma cada gesto rápido de la terminal con --resume.

Lo que cambia el modo headless en octubre de 2026

Desde octubre de 2026, claude -p y el Agent SDK sin modo de permiso configurado arrancan en modo default: una llamada que necesita aprobación se rechaza allí, salvo que una regla de autorización, un hook o la opción --permission-prompt-tool la conceda. Un script que modifica archivos debe, pues, pasar --permission-mode o llevar una regla. Además, el límite de duración de los comandos en segundo plano solo se aplica ya a las sesiones sin supervisión (-p, SDK, CI, nube): una sesión de terminal, de escritorio o de VS Code ya no tiene límite.