Ejecutar Claude Code mediante programación

El Agent SDK le proporciona las mismas herramientas, bucle de agente y gestión de contexto que potencian Claude Code. Está disponible como CLI para scripts e CI/CD, o como paquetes de Python y TypeScript para control programático completo. Para ejecutar Claude Code en modo no interactivo, pase -p con su indicación y las opciones de CLI que necesite:

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

Esta página cubre el uso del Agent SDK a través de la CLI (claude -p). Para los paquetes SDK de Python y TypeScript con salidas estructuradas, devoluciones de llamada de aprobación de herramientas y objetos de mensaje nativos, consulte la documentación completa del Agent SDK.

Uso básico

Agrega la bandera -p (o --print) a cualquier comando claude para ejecutarlo de forma no interactiva. No todas las opciones de CLI se combinan con -p. Claude Code rechaza --bg, y rechaza --cloud con una descripción de tarea, con un error que nombra el conflicto; --cloud con un ID de sesión y -p en su lugar pone en cola un mensaje en esa sesión en la nube y sale. Las opciones que combinarás con -p a menudo incluyen:

--continue para continuar conversaciones
--allowedTools para aprobar herramientas automáticamente
--output-format para obtener salida estructurada

Este ejemplo le pregunta a Claude sobre tu base de código e imprime la respuesta:

claude -p "What does the auth module do?"

Claude Code sale con código 0 en caso de éxito y con un código distinto de cero cuando la ejecución falla, por lo que tus scripts pueden actuar según el estado de salida. Si pasas una bandera inválida, Claude Code reporta el error a stderr antes de que comience la ejecución. Cuando ocurre una falla dentro de la ejecución, como autenticación faltante, Claude Code imprime la falla como resultado en stdout.

Comienza más rápido con modo bare

Agrega --bare para reducir el tiempo de inicio omitiendo el descubrimiento automático de hooks, skills, comandos personalizados, subagentes, plugins instalados, servidores MCP, memoria automática y CLAUDE.md. Sin él, claude -p los descubre y los carga como lo haría una sesión interactiva, incluido cualquier elemento configurado en el directorio de trabajo o ~/.claude. El modo bare es útil para CI y scripts donde necesitas el mismo resultado en cada máquina. Un hook en ~/.claude de un compañero de equipo o un servidor MCP en .mcp.json del proyecto no se ejecutará, porque el modo bare nunca los lee. Un directorio que nombres con --add-dir es una excepción parcial: el modo bare carga skills de su carpeta .claude/skills/, pero aún omite sus carpetas .claude/commands/ y .claude/agents/. Skills de directorios adicionales cubre lo que sí y no se carga. Sin --bare, una sesión -p ejecuta los hooks en .claude/settings.json de un proyecto y conecta los servidores en su .mcp.json, incluso en una carpeta en la que nunca has confiado. Una sesión -p no muestra diálogo de confianza del espacio de trabajo ni solicitud de aprobación por servidor. Lo que se ejecuta antes de confiar en una carpeta cubre cada tipo de contenido del repositorio bajo -p y cómo mantenerlo fuera. Este ejemplo ejecuta una tarea de resumen única en modo bare y aprueba previamente la herramienta Read para que la llamada se complete sin una solicitud de permiso. Establece ANTHROPIC_API_KEY antes de ejecutarlo, porque el modo bare no usa tu inicio de sesión de suscripción:

claude --bare -p "Summarize README.md" --allowedTools "Read"

En modo bare, Claude Code nunca lee credenciales OAuth ni el llavero del sistema. Para la API de Anthropic, establece ANTHROPIC_API_KEY en el entorno, con una clave creada en la Consola de Claude, o proporciona un apiKeyHelper en el JSON --settings. Amazon Bedrock, Agent Platform de Google Cloud y Microsoft Foundry continúan leyendo sus propias credenciales de proveedor como de costumbre. En modo bare, Claude tiene acceso a las herramientas Bash, lectura de archivos y edición de archivos. Pasa el contexto que necesites con una bandera:

Para cargar	Usar
Adiciones al prompt del sistema	`--append-system-prompt`, `--append-system-prompt-file`
Configuración	`--settings <file-or-json>`
Servidores MCP	`--mcp-config <file-or-json>`
Agentes personalizados	`--agents <file-or-json>`
Un plugin	`--plugin-dir <path>`, `--plugin-url <url>`

Los hooks siguen sin ejecutarse en modo bare cuando los pasas con --settings, o en el hooks/hooks.json o la clave hooks del manifiesto de un plugin que cargas con una bandera. No uses el modo bare para una ejecución que los necesite. El modo bare también limita lo que ocurre mientras se ejecuta la sesión:

Servidores MCP: solo se conectan los servidores proporcionados en la línea de comandos, por ejemplo con --mcp-config. En una sesión interactiva, Claude Code también omite la conexión automática con el IDE a menos que pases --ide.
Recordatorios del sistema: Claude recibe tus prompts y los resultados de las herramientas sin los recordatorios del sistema que Claude Code agregaría junto a ellos. Por ejemplo, a Claude no se le informa cuando un archivo que leyó antes cambia en el disco, y no recibe la lista de skills disponibles, incluidos los skills de una carpeta de --add-dir.
Tareas en segundo plano: Claude no puede ejecutar comandos en segundo plano ni subagentes en segundo plano, y las demás funciones que CLAUDE_CODE_DISABLE_BACKGROUND_TASKS desactiva también quedan desactivadas. Un comando que alcanza su tiempo de espera se detiene en lugar de pasar a segundo plano.

Antes de la v2.1.286, estos límites se aplicaban solo en parte: una sesión interactiva con --bare conectaba los servidores MCP que conectaría una sesión normal, cada sesión con --bare enviaba recordatorios del sistema y las tareas en segundo plano seguían disponibles.

--bare es el modo recomendado para llamadas con scripts y SDK, y se convertirá en el predeterminado para -p en una versión futura.

Tareas en segundo plano al salir

Después de que Claude termina su turno y stdin se ha cerrado, una ejecución claude -p puede permanecer abierta para esperar el trabajo en segundo plano que Claude inició. A menos que siga ejecutándose un comando en segundo plano que haya iniciado la conversación principal, de forma predeterminada Claude Code detiene lo que aún se esté ejecutando después de 10 minutos de espera inactiva continua y descarta su resultado parcial. Para cambiar el límite de 10 minutos, establece CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS, o establécelo en 0 para esperar sin límite. La ejecución espera trabajo en segundo plano como comandos en segundo plano, subagentes y flujos de trabajo, vigilancias de Monitor y activaciones pendientes de /loop:

Comandos en segundo plano: para un comando que inició la conversación principal, por ejemplo un servidor de desarrollo o una compilación de vigilancia, la ejecución espera hasta que el comando sale o alcanza su límite de tiempo. Luego Claude toma un turno más con el resultado. Mientras el comando se ejecuta, el límite de 10 minutos no finaliza la espera.
Subagentes y flujos de trabajo en segundo plano: la ejecución permanece abierta hasta que cada uno termine o el límite de 10 minutos finalice la espera.
Vigilancias de Monitor: la ejecución espera hasta que se agote el tiempo de espera de la vigilancia o el límite de 10 minutos finalice la espera, lo que ocurra primero. Mientras espera, Claude continúa respondiendo a lo que reporta la vigilancia. De forma predeterminada, el tiempo de espera de una vigilancia se agota cinco minutos después de que Claude la inicia.
Activaciones pendientes: en una ejecución cuyo prompt pasaste como texto en lugar de con --input-format stream-json, cuando Claude ha programado una activación de /loop a su propio ritmo, la ejecución espera a que se dispare cada activación y ejecuta su iteración hasta que el bucle termina, incluso más allá del límite de 10 minutos.

Cuando stderr es una terminal y la ejecución ha esperado cinco segundos, Claude Code imprime en stderr una línea que comienza con Waiting for background work to finish y nombra el trabajo. Con salida json o stream-json, la línea se imprime solo cuando stdout no es una terminal, por lo que el JSON que lee tu script nunca la incluye. Si la ejecución alcanza su límite de --max-budget-usd, Claude Code detiene el trabajo en segundo plano restante en lugar de esperar. Cuando el trabajo en segundo plano inicia otro turno, la ejecución imprime el resultado de cada turno con la salida text predeterminada y el resultado del último turno con la salida json. Antes de la v2.1.295, la ejecución también imprimía solo el resultado del último turno con la salida text.

Dale más tiempo al comando largo de un subagente

Cuando el comando largo de un subagente pasa a segundo plano al agotarse su tiempo de espera, sigue ejecutándose, pero una ejecución claude -p puede salir con código 0 antes de que el comando termine. Para aumentar el tiempo de espera predeterminado por encima del tiempo de ejecución del comando, establece BASH_DEFAULT_TIMEOUT_MS, por ejemplo BASH_DEFAULT_TIMEOUT_MS=300000 claude -p "<prompt>" para cinco minutos. Para un comando de un subagente en segundo plano que dure más de 10 minutos, aumenta también el límite de 10 minutos.

Trabajo MCP cuando termina una ejecución no interactiva

Una ejecución claude -p no espera el trabajo MCP en segundo plano:

Tareas MCP: en un servidor remoto, el trabajo continúa. Para volver a seguirlo, reanuda esa sesión, no como una ejecución única claude -p "<prompt>".
Llamadas MCP que movió el paso automático a segundo plano: el resultado de la llamada se pierde.

Detener una ejecución con SIGTERM

Si detienes una ejecución claude -p con SIGTERM, por ejemplo con kill o desde un supervisor de procesos, Claude Code sale con código 143. Claude Code deja el turno que estaba en progreso sin terminar y no registra ningún resultado para él. Para terminar el turno en su lugar, envía SIGINT, o llama a interrupt() del Agent SDK, antes de detener el proceso. En SIGTERM, Claude Code termina el árbol de procesos de cualquier comando Bash que aún se esté ejecutando. Claude Code luego ejecuta hooks SessionEnd y sale. Al salir, Claude Code no inicia ninguna nueva llamada a herramienta, no envía ninguna nueva solicitud al modelo y no ejecuta ningún hook que no sea SessionEnd. Si la ejecución estaba en medio de un comando o esperando una solicitud de permiso cuando llegó la señal, Claude Code maneja ese paso de la siguiente manera:

Ejecutando un comando: Claude Code registra el comando como terminado en la sesión.
Esperando una respuesta a una solicitud de permiso: si envías SIGTERM al proceso, Claude Code deja la solicitud sin responder. Si tu programa cierra la sesión a través del Agent SDK, el SDK finaliza la entrada de Claude Code antes de enviar cualquier señal, y Claude Code cancela la solicitud tan pronto como finaliza la entrada.

Cuando reanudas la sesión, Claude Code deja el turno interrumpido tal como está, y tu siguiente prompt impulsa la conversación. Para que Claude Code continúe el turno interrumpido al reanudar, establece CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1.

Si el directorio de trabajo se elimina

Si el directorio de trabajo de una sesión claude -p o Agent SDK se elimina durante la sesión, la sesión continúa ejecutándose. Cuando un turno comienza mientras falta el directorio, Claude Code emite un mensaje de advertencia en la salida stream-json, y los comandos de shell fallan hasta que el directorio exista nuevamente.

Ejemplos

Estos ejemplos destacan patrones comunes de CLI. Donde un comando nombra un archivo como auth.py o build-error.txt, sustituye un archivo de tu propio proyecto. En CI u otros entornos con scripts, agrega --bare para que Claude Code se inicie sin cargar los hooks del host, plugins, memoria automática o CLAUDE.md.

Canalizar datos a través de Claude

El modo no interactivo lee stdin, por lo que puedes canalizar datos y redirigir la respuesta como cualquier otra herramienta de línea de comandos. Este ejemplo canaliza un registro de compilación a Claude y escribe la explicación en un archivo:

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

Con --output-format json, la carga útil de respuesta incluye total_cost_usd y un desglose de costos por modelo, por lo que los llamadores con scripts pueden rastrear el gasto sin consultar el panel de uso. Cuando continúas una conversación anterior con --continue o --resume, la ejecución informa el total completo de la conversación, gastos de ejecuciones anteriores incluidos. Ambas cifras son estimaciones del lado del cliente y pueden diferir de tu factura real.

El stdin canalizado está limitado a 10MB. Si excedes el límite, Claude Code sale con un error claro y un estado distinto de cero. Para trabajar con entradas más grandes, escribe el contenido en un archivo y haz referencia a la ruta del archivo en tu prompt en lugar de canalizarlo.

Si Claude Code no puede leer stdin, por ejemplo porque el proceso que lo inició desconectó su extremo, Claude Code imprime una advertencia en stderr y continúa con el prompt de la línea de comandos.

Agregar Claude a un script de compilación

Puedes envolver una llamada no interactiva en un script para usar Claude como un linter o revisor específico del proyecto. Este script package.json canaliza el diff contra main a Claude y le pide que informe sobre errores tipográficos. Canalizar el diff significa que Claude no necesita permiso de Bash para leerlo, y las comillas dobles escapadas mantienen el script portátil a Windows:

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
  }
}

Ejecútalo con npm run lint:claude.

Obtener salida estructurada

Usa --output-format para controlar cómo se devuelven las respuestas:

text (predeterminado): salida de texto sin formato
json: JSON estructurado con resultado, ID de sesión y metadatos
stream-json: JSON delimitado por saltos de línea para streaming en tiempo real

Este ejemplo devuelve un resumen del proyecto como JSON con metadatos de sesión, con el resultado de texto en el campo result:

claude -p "Summarize this project" --output-format json

Para obtener una salida que se ajuste a un esquema específico, usa --output-format json con --json-schema y una definición de JSON Schema. La respuesta incluye metadatos sobre la solicitud (ID de sesión, uso, etc.) con la salida estructurada en el campo structured_output. Este ejemplo extrae nombres de funciones y los devuelve como una matriz de cadenas:

claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

Si el valor no es un JSON Schema válido, claude sale con Error: --json-schema is not a valid JSON Schema seguido del diagnóstico del validador. Claude Code acepta esquemas que utilizan la palabra clave format, como "format": "email", pero trata format como una anotación y no la aplica. Si una ejecución termina sin una salida estructurada válida, por ejemplo porque Claude rechazó la solicitud, la respuesta no tiene el campo structured_output. Antes de que tu script use structured_output, comprueba que el campo esté presente.

Usa una herramienta como jq para analizar la respuesta y extraer campos específicos:

# Extract the text result
claude -p "Summarize this project" --output-format json | jq -r '.result'

# Extract structured output
claude -p "Extract function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

Respuestas en streaming

Usa --output-format stream-json con --verbose e --include-partial-messages para recibir tokens a medida que se generan. Cada línea es un objeto JSON que representa un evento:

claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages

La última línea del stream es un mensaje result con el texto de respuesta final, el costo y los metadatos de la sesión. Si tu consumidor lee el stream lentamente, Claude Code espera a que se drene la salida en cola antes de salir, escalando la espera según cuánto sigue en cola, con un límite de 30 segundos. El siguiente ejemplo usa jq para filtrar deltas de texto y mostrar solo el texto en streaming. El flag -r genera cadenas sin formato (sin comillas) y -j une sin saltos de línea para que los tokens se transmitan en streaming de forma continua:

claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

Para streaming programático con devoluciones de llamada y objetos de mensaje, consulta Respuestas en streaming en tiempo real en la documentación del Agent SDK.

Seguir mensajes de subagentes

Los mensajes de subagentes y de skills que se ejecutan en un subagente aparecen en el stream como mensajes assistant y user. Su campo parent_tool_use_id indica a qué ejecución pertenece cada uno. Los mensajes de la conversación principal llevan null en ese campo. El primer mensaje de un skill bifurcado, o de un subagente que se ejecuta en primer plano, es un mensaje user que lleva el prompt o el contenido del skill que lo impulsa. Después de ese primer mensaje, Claude Code emite:

De forma predeterminada: los bloques tool_use y tool_result de la ejecución.
Con --forward-subagent-text o CLAUDE_CODE_FORWARD_SUBAGENT_TEXT: también los bloques de texto y pensamiento de la ejecución, para que puedas reconstruir la transcripción de cada ejecución.

Cuando habilitas cualquiera de las opciones, Claude Code reenvía mensajes de subagentes en cada nivel de anidamiento, ya sea que cada uno se haya generado con la herramienta Agent o se haya iniciado como un skill bifurcado. En parent_tool_use_id, los mensajes del subagente anidado llevan el ID de la llamada a la herramienta Agent o Skill que lo inició, para que puedas reconstruir el árbol de anidamiento completo siguiendo esos IDs. Una ejecución que Claude inicia con una llamada a herramienta lleva el ID de esa llamada. Un skill bifurcado que inicias pasando /<skill-name> como prompt no tiene llamada a herramienta, así que sus mensajes llevan en su lugar un valor forked-command- y llegan después de que termina. Busca en la primera columna cómo comenzó la ejecución:

Cómo comienza la ejecución	`parent_tool_use_id`	Cuándo llegan sus mensajes
Claude llama a la herramienta Agent desde la conversación principal	El ID de ese bloque `tool_use` de Agent	Mientras el subagente trabaja
Claude llama a la herramienta Skill para un skill bifurcado desde la conversación principal	El ID de ese bloque `tool_use` de Skill	Mientras el skill bifurcado trabaja
Pasas `/<skill-name>` como prompt	Un valor que comienza con `forked-command-`	Juntos y en orden después de que el skill bifurcado termina

Para un skill bifurcado iniciado desde el prompt, haz coincidir parent_tool_use_id con el prefijo forked-command-, porque el nombre que le sigue puede diferir del que escribiste. Si faltan algunos de estos mensajes en tu stream, compara tu versión de Claude Code con estos mínimos:

Un skill bifurcado que Claude inicia con la herramienta Skill desde la conversación principal: v2.1.86 o posterior para sus bloques tool_use y tool_result, y v2.1.265 o posterior para su primer mensaje user y sus bloques de texto y pensamiento
Mensajes de subagentes que genera un skill bifurcado, y de skills bifurcados iniciados dentro de un subagente u otro skill bifurcado: v2.1.275 o posterior
Mensajes de un skill bifurcado que inicias pasando /<skill-name> como prompt: v2.1.287 o posterior

Manejar reintentos de API

Cuando una solicitud de API falla con un error reintentable, Claude Code emite un evento system/api_retry antes de reintentar. En v2.1.246 o posterior, cuando un 401 o 403 rechaza una credencial apiKeyHelper, Claude Code realiza los primeros dos reintentos silenciosamente sin evento, luego emite el evento como de costumbre desde el tercer reintento consecutivo en adelante. Los reintentos silenciosos aún cuentan para attempt. Puedes usar el evento para mostrar el progreso del reintento en tu propia interfaz.

Campo	Tipo	Descripción
`type`	`"system"`	tipo de mensaje
`subtype`	`"api_retry"`	identifica esto como un evento de reintento
`attempt`	entero	número de intento actual, comenzando en 1
`max_retries`	entero	reintentos totales permitidos para la causa de este fallo
`retry_delay_ms`	entero	milisegundos hasta el siguiente intento
`error_status`	entero o nulo	código de estado HTTP del intento fallido, o `null` cuando el intento no obtuvo respuesta HTTP de la API
`no_response`	objeto, opcional	presente solo cuando el intento fallido no obtuvo encabezados de respuesta a tiempo. `waited_ms` es cuánto tiempo esperó ese intento y `retry_wait_ms` es cuánto tiempo esperará el reintento. Requiere Claude Code v2.1.261 o posterior
`error`	cadena	categoría de error: `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `rate_limit`, `overloaded`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error`, o `unknown`
`uuid`	cadena	identificador único del evento
`session_id`	cadena	sesión a la que pertenece el evento

Leer metadatos de sesión

El evento system/init informa metadatos de sesión incluyendo el modelo, herramientas, servidores MCP y plugins cargados. Es el primer evento en el stream a menos que eventos de inicio lo precedan:

eventos plugin_install, cuando CLAUDE_CODE_SYNC_PLUGIN_INSTALL está configurado.
eventos hook_started, hook_progress y hook_response, mientras se ejecuta un hook SessionStart o Setup configurado. Estos se transmiten en streaming a medida que el hook los produce.

El evento también lleva una matriz capabilities opcional de cadenas que nombran los comportamientos del protocolo que esta versión de Claude Code implementa, como interrupt_receipt_v1 o interrupt_cancel_queued_v1. Revísala para detectar características en lugar de comparar cadenas de versión, e ignora los valores que no reconozcas. Consulta SDKSystemMessage para la lista de capacidades.

Hacer fallar CI cuando un plugin o servidor MCP no se carga

Usa los campos de plugin en el evento system/init para detectar un plugin que no se cargó:

Campo	Tipo	Descripción
`plugins`	matriz	plugins que se cargaron exitosamente, cada uno con `name` y `path`
`plugin_errors`	matriz	errores de tiempo de carga de plugin, cada uno con `plugin`, `type` y `message`. Incluye versiones de dependencia insatisfechas y fallos de carga de `--plugin-dir` como una ruta faltante o un archivo comprimido inválido. Un plugin que no se cargó está ausente de `plugins`. La clave se omite cuando no hay errores

Cuando un directorio o archivo comprimido de --plugin-dir en sí falla al cargarse, su entrada plugin_errors incluye la ruta absoluta resuelta como path. Úsala para saber cuál de varios valores --plugin-dir falló. El campo path requiere Claude Code v2.1.283 o posterior. Usa los campos del servidor MCP de la misma manera. Cuando pasas --mcp-config con -p, Claude Code espera a los servidores aún pendientes antes de ejecutar el primer turno, hasta el tiempo de espera de inicio MCP_TIMEOUT, 30 segundos de forma predeterminada. Un servidor remoto con una lista de herramientas en caché omite la espera, muestra pending en system/init y se conecta en su primera llamada a herramienta. En un entorno autoalojado, se aplica en su lugar una espera más corta. La espera requiere Claude Code v2.1.221 o posterior. Claude Code valida cada entrada --mcp-config al inicio y omite las entradas que no pasan la validación, por ejemplo una entrada url sin type. La ejecución continúa y sale limpiamente, así que revisa estos campos para detectar un servidor que nunca se cargó:

Campo	Tipo	Descripción
`mcp_servers`	matriz	servidores MCP en la sesión, cada uno con `name` y `status`
`mcp_server_errors`	matriz	entradas `--mcp-config` omitidas por la validación de configuración, cada una con `name`, `type` y `message`. `type` es una categoría de omisión como `unknown_type`, `url_missing_type`, `invalid_config` o `reserved_name`; trata los valores que no reconozcas como una omisión genérica. Los servidores afectados están ausentes de `mcp_servers`. La clave se omite cuando no hay errores, por lo que una puerta de CI puede fallar ante una matriz no vacía

Cuando ejecutas el comando a mano en una terminal, Claude Code también imprime una advertencia de inicio en stderr, como Warning: 1 MCP server skipped due to invalid config:, seguida de la razón de cada entrada omitida. Cuando rediriges stderr, o cuando un programa como un ejecutor de CI o un host del SDK lo captura, Claude Code no imprime ninguna advertencia. Informa las entradas omitidas solo en el campo mcp_server_errors.

Rastrear instalaciones de plugins

Cuando CLAUDE_CODE_SYNC_PLUGIN_INSTALL está configurado, Claude Code emite eventos system/plugin_install mientras los plugins del marketplace se instalan antes del primer turno. Úsalos para mostrar el progreso de instalación en tu propia interfaz de usuario.

Campo	Tipo	Descripción
`type`	`"system"`	tipo de mensaje
`subtype`	`"plugin_install"`	identifica esto como un evento de instalación de plugin
`status`	`"started"`, `"installed"`, `"failed"`, o `"completed"`	`started` y `completed` enmarcan la instalación general; `installed` y `failed` informan sobre marketplaces individuales
`name`	cadena, opcional	nombre del marketplace, presente en `installed` y `failed`
`error`	cadena, opcional	mensaje de fallo, presente en `failed`
`uuid`	cadena	identificador único del evento
`session_id`	cadena	sesión a la que pertenece el evento

Aprobar herramientas automáticamente

Usa --allowedTools para permitir que Claude use ciertas herramientas sin pedir confirmación. Enumerar Read y Edit permite que Claude lea y edite archivos sin pedir permiso, salvo las lecturas desde rutas de red. Enumerar Bash hace lo mismo para comandos de shell, excepto en una ejecución que comienza en modo automático, donde Claude Code descarta una entrada Bash sin más como una regla de permisos demasiado amplia y el modo automático evalúa cada comando en su lugar. Este ejemplo ejecuta un conjunto de pruebas y corrige fallos con esas tres herramientas enumeradas:

claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

Las llamadas a herramientas que no enumeraste se ejecutan si no necesitan aprobación. En una ejecución claude -p en modo Manual, una llamada que necesita aprobación se deniega a menos que algo la apruebe, como un hook PermissionRequest o un --permission-prompt-tool. Con Claude Code v2.1.302 o posterior, las ejecuciones claude -p comienzan en modo Manual cuando nada establece un modo de permisos. Para establecer una línea base para toda la sesión en lugar de enumerar herramientas individuales, pasa un modo de permisos con --permission-mode, como auto, dontAsk o acceptEdits:

auto: pasa --permission-mode auto para que un clasificador revise la mayoría de las acciones en lugar de ti
dontAsk: Claude Code deniega cualquier llamada que de otro modo pediría confirmación, lo que es útil para ejecuciones de CI bloqueadas, aunque un mod que instalaste aún puede aprobar algunas de esas llamadas. Para comprobar qué llamadas puede aprobar un mod, consulta Extender permisos con hooks. Las acciones que no necesitan aprobación en modo Manual aún se ejecutan, como lecturas de archivos en tus directorios de trabajo y el conjunto de comandos de solo lectura. Las acciones que cubren tus entradas --allowedTools o reglas permissions.allow también se ejecutan. AskUserQuestion, las herramientas de conector que tu organización configuró como ask, las herramientas MCP marcadas con requiresUserInteraction y las lecturas desde rutas de red se deniegan incluso cuando coincide una regla de permisos
acceptEdits: Claude escribe archivos sin pedir confirmación, y Claude Code aprueba automáticamente comandos comunes del sistema de archivos como mkdir, touch, mv y cp. Las acciones que ningún modo aprueba automáticamente aún se aplican. Aparte del conjunto de comandos de solo lectura, otros comandos de shell y solicitudes de red aún necesitan una entrada --allowedTools o una regla permissions.allow. Consulta qué aprueba automáticamente acceptEdits para la lista completa

Este ejemplo aplica correcciones de lint con acceptEdits como línea base:

claude -p "Apply the lint fixes" --permission-mode acceptEdits

Desactivar las solicitudes de permiso en ejecuciones desatendidas

Pasa --permission-prompts none cuando nadie esté disponible para responder solicitudes de permiso, por ejemplo en un trabajo programado. El flag importa sobre todo cuando tu ejecución tiene un host de permisos: una aplicación del Agent SDK con una devolución de llamada canUseTool, o una herramienta MCP que pasas con --permission-prompt-tool. Sin el flag, tu ejecución espera a que ese host responda cada solicitud de permiso. Con el flag, tu ejecución no consulta al host ni lo espera. Cualquier cosa que pediría confirmación se deniega a menos que un hook PermissionRequest la permita, se le indica a Claude que nadie puede aprobar la solicitud y que no la reintente, y la ejecución continúa. En una ejecución -p sin host, estas solicitudes se deniegan de cualquier forma, y el flag también le indica a Claude que no las reintente. Las reglas de permisos, los hooks PermissionRequest y el modo de permisos que establezcas siguen decidiendo primero cada llamada; Claude Code deniega solo las solicitudes que nada más resuelve. Este ejemplo ejecuta una tarea desatendida en modo automático. El clasificador revisa cada acción como de costumbre, y Claude Code deniega cualquier cosa que habría terminado en una solicitud de permiso:

claude -p "Update the dependency pins and run the tests" --permission-mode auto --permission-prompts none

Con --permission-prompts none, Claude Code elimina las herramientas que necesitan una respuesta de una persona, como AskUserQuestion, por lo que Claude no puede llamarlas. Cualquier solicitud de elicitación MCP que ningún hook Elicitation responda se cancela. Con --output-format stream-json, las denegaciones aparecen como mensajes del sistema permission_denied, y el mensaje de resultado final las enumera en permission_denials.

El flag --permission-prompts requiere Claude Code v2.1.259 o posterior. Las versiones anteriores lo rechazan con un error de opción desconocida.

Crear un commit

Este ejemplo revisa los cambios preparados y crea un commit con un mensaje apropiado:

claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

El flag --allowedTools utiliza la sintaxis de reglas de permisos. El * final habilita la coincidencia de prefijo, por lo que Bash(git diff *) permite cualquier comando que comience con git diff. El espacio antes de * es importante: sin él, Bash(git diff*) también coincidiría con git diff-index.

La compatibilidad de comandos difiere en modo -p:

Los skills invocados por el usuario y los comandos personalizados funcionan. Incluye /skill-name en la cadena del prompt y Claude Code lo expande antes de ejecutar.
Los comandos integrados que solo se ejecutan en la interfaz de la terminal, como /login, no están disponibles.
/model, /effort, /fast, /color y /rename aceptan el valor como argumento, por ejemplo /model sonnet, y /mcp sin argumento imprime un resumen de texto del estado del servidor. Estas formas siguen las notas de disponibilidad de cada comando.
Para cambiar un ajuste, pasa key=value a /config, por ejemplo /config verbose=true.
/output-style <style> cambia de estilo de salida y /output-style solo los enumera. Requiere Claude Code v2.1.269 o posterior.

Personalizar el prompt del sistema

Usa --append-system-prompt para agregar instrucciones mientras mantienes el comportamiento predeterminado de Claude Code. Este ejemplo canaliza el diff de un PR a Claude y le indica que lo revise en busca de vulnerabilidades de seguridad. Guárdalo como un script de shell, por ejemplo review.sh:

gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json

En el script, "$1" representa el primer argumento que pasas en la línea de comandos. Ejecuta bash review.sh 123 y el shell reemplaza "$1" con 123, por lo que el script obtiene el diff del PR 123. Claude Code imprime la revisión como JSON, con el texto en el campo result. Consulta flags del prompt del sistema para más opciones, incluido --system-prompt para reemplazar completamente el prompt predeterminado. Si lo reemplazas, la ejecución también comienza sin la instantánea del estado de git.

Continuar conversaciones

Usa --continue para continuar la conversación más reciente, o --resume con un ID de sesión para continuar una conversación específica. En Claude Code v2.1.257 o posterior, cuando pasas --continue, Claude Code abre una sesión en segundo plano que ha terminado, pero no una que aún se está ejecutando. Este ejemplo ejecuta una revisión y luego envía prompts de seguimiento:

# First request
claude -p "Review this codebase for performance issues"

# Continue the most recent conversation
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue

Si estás ejecutando múltiples conversaciones, captura el ID de sesión para reanudar una específica:

session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

Puedes ejecutar los dos comandos desde directorios diferentes: Claude Code encuentra la sesión por su ID en cualquier proyecto de esta máquina. En lugar del ID de sesión, puedes pasar a --resume la ruta absoluta al archivo de transcripción .jsonl de una sesión, y Claude Code continúa la conversación almacenada en ese archivo.

Próximos pasos

Inicio rápido del Agent SDK: construya su primer agente con Python o TypeScript
Referencia de CLI: todas las banderas y opciones de CLI
GitHub Actions: utilice el Agent SDK en flujos de trabajo de GitHub
GitLab CI/CD: utilice el Agent SDK en canalizaciones de GitLab

Agentes y trabajo en paralelo

MCP

Skills

Artefactos

Automatización

Guías

Solución de problemas

Ejecutar Claude Code mediante programación

Uso básico

Comienza más rápido con modo bare

Tareas en segundo plano al salir

Dale más tiempo al comando largo de un subagente

Trabajo MCP cuando termina una ejecución no interactiva

Detener una ejecución con SIGTERM

Si el directorio de trabajo se elimina

Ejemplos

Canalizar datos a través de Claude

Agregar Claude a un script de compilación

Obtener salida estructurada

Respuestas en streaming

Seguir mensajes de subagentes

Manejar reintentos de API

Leer metadatos de sesión

Hacer fallar CI cuando un plugin o servidor MCP no se carga

Rastrear instalaciones de plugins

Aprobar herramientas automáticamente

Desactivar las solicitudes de permiso en ejecuciones desatendidas

Crear un commit

Personalizar el prompt del sistema

Continuar conversaciones

Próximos pasos