Ir al contenido
Mastering Claude

El curso175 lecciones

Inicio / Gestos cotidianos

Gestos cotidianos9 minAplicación

Modo headless, formatos 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. 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, y la documentación oficial lo recomienda para las llamadas con script. Contrapartida: el modo bare nunca lee los identificadores OAuth ni el llavero del sistema, así que un script que lo use debe fijar la variable ANTHROPIC_API_KEY para autenticarse ante la API de Anthropic.

Una llamada mínima cuando --bare queda descartado

Con una suscripción, --bare no sirve, porque no lee la conexión. Entonces se quitan las fuentes una a una, con indicadores que claude --help lista en la versión 2.1.325:

claude -p "Responde con una palabra" --output-format json \
  --system-prompt "Responde en una palabra." --tools "" \
  --strict-mcp-config --disable-slash-commands --no-session-persistence

El prompt de sistema por defecto se sustituye, las herramientas integradas se quitan, las skills y los comandos se desactivan y la sesión no se guarda. La ayuda no dice que estos indicadores ignoren los archivos CLAUDE.md: solo --bare lo dice. Mide: compara los campos input_tokens y cache_creation_input_tokens del objeto usage entre la llamada por defecto y la llamada mínima.

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.

Las tareas que exponen los servidores MCP también pasan por /tasks. Desde la versión 2.1.325, Claude recibe el aviso cuando una de estas tareas espera tu respuesta, y puede remitirte a /tasks para verla y responder.

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 que empiece por sleep. La variable CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 y el modo --bare desactivan el cambio: el comando se detiene entonces en su plazo (referencia de herramientas, releída el 2026-11-16). 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.

El código de salida sigue estos rechazos. En modo auto, cuando las acciones de claude -p se rechazan porque no hay ninguna comprobación de seguridad disponible, el comando termina con el código 1, tanto en salida de texto como en JSON (registro de cambios, versión 2.1.319); antes terminaba con 0. Un script que comprueba el código de salida ve así el fallo, mientras que un script antiguo podía creer que había tenido éxito.

Figura 1

De un comando headless a una salida utilizable por un script

01
Entrada en modo headless
El indicador -p envía un prompt a Claude Code sin abrir una interfaz interactiva.
02
Ejecución no interactiva
Claude Code procesa la solicitud solo, sin esperar una respuesta humana entre los pasos.
03
Salida elegida
El parámetro --output-format determina si el resultado sale en texto, en un único objeto JSON, o en JSON Lines en flujo.
04
El script lee el resultado
Un programa externo recupera la salida estructurada, con el costo total y el identificador de sesión, sin analizar texto libre.
05
Comando largo en tarea de fondo
Si un paso dura demasiado, run_in_background lo hace continuar mientras el script queda libre para lo que sigue.
La secuencia muestra cómo una solicitud enviada en modo headless atraviesa una ejecución no interactiva hasta llegar a una salida estructurada que un script puede leer, con un posible cambio a tarea en segundo plano si un paso dura demasiado.
Calíbralo tú mismo

Un desarrollador lanza claude -p con --output-format json en un pipeline de despliegue, y el script del pipeline recupera el campo total_cost_usd del resultado para añadirlo al panel de costos.

Escribe en una frase lo que esta situación establece, y en una frase lo que no establece.

Lo que hay que recordar
  • Un script con claude -p sin modo configurado arranca en default y ve rechazada toda llamada que necesite aprobación: pasa --permission-mode o una regla.
  • --output-format json devuelve un objeto único que contiene el resultado, el identificador de sesión y el costo total en dólares con su desglose por modelo.
  • --bare se salta el descubrimiento automático de hooks, skills y archivos de contexto al arrancar, una ganancia de velocidad recomendada para las llamadas con script, pero nunca lee los identificadores OAuth ni el llavero, por lo que ANTHROPIC_API_KEY se vuelve necesaria; con una suscripción, una llamada mínima se arma a mano con --system-prompt, --tools y --strict-mcp-config.
  • run_in_background devuelve inmediatamente un identificador de tarea y deja que un comando largo continúe; un comando que llega a su plazo de expiración cambia solo a tarea en segundo plano, salvo que empiece por sleep, y CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 o --bare desactivan el cambio. Una tarea MCP que espera tu respuesta se señala a Claude, que puede remitirte a /tasks.
  • En modo auto, claude -p termina con el código 1 cuando sus acciones se rechazan porque no hay ninguna comprobación de seguridad disponible: comprueba el código de salida en tus scripts.
Hazlo ahora

Lanza desde tu terminal claude -p "una palabra al azar" --output-format json en una carpeta que no contenga ningún dato sensible, y localiza en la salida los campos session_id y total_cost_usd.

Verificar en la fuente

Cada afirmación datable de esta lección remite aquí al texto público que la respalda. Una fuente que no se abre no prueba nada.