Ejecutar Claude Code mediante programación

Utilice el Agent SDK para ejecutar Claude Code mediante programación desde la CLI, Python o TypeScript.

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

Agregue 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á 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 su 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 sus scripts pueden ramificarse según el estado de salida. Si pasa 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.

Comenzar más rápido con modo bare

Agregue --bare para reducir el tiempo de inicio omitiendo el descubrimiento automático de hooks, skills, comandos personalizados, subagentes, plugins, servidores MCP, memoria automática y CLAUDE.md. Sin él, claude -p carga el mismo contexto que una sesión interactiva, incluyendo cualquier cosa configurada en el directorio de trabajo o ~/.claude.

El modo bare es útil para CI y scripts donde necesita el mismo resultado en cada máquina. Un hook en el ~/.claude de un compañero de equipo o un servidor MCP en el .mcp.json del proyecto no se ejecutarán, porque el modo bare nunca los lee. Un directorio que nombre 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 qué se carga y qué no.

Sin --bare, una sesión -p ejecuta los hooks en el .claude/settings.json de un proyecto y conecta los servidores en su .mcp.json, incluso en una carpeta que nunca ha 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. Establezca ANTHROPIC_API_KEY antes de ejecutarlo, porque el modo bare no usa su 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, establezca ANTHROPIC_API_KEY en el entorno, con una clave creada en la Consola de Claude, o proporcione un apiKeyHelper en el JSON de --settings. Amazon Bedrock, Google Cloud's Agent Platform y Microsoft Foundry continúan leyendo sus credenciales de proveedor habituales como de costumbre.

En modo bare Claude tiene acceso a las herramientas Bash, lectura de archivos y edición de archivos. Pase cualquier contexto que necesite con una bandera:

Tareas en segundo plano al salir

Si Claude inicia una tarea Bash en segundo plano durante una ejecución de claude -p, por ejemplo un servidor de desarrollo o una compilación de vigilancia, ese shell se termina aproximadamente cinco segundos después de que Claude haya devuelto su resultado final y stdin se haya cerrado. El período de gracia permite que una tarea que finaliza justo después del resultado aún entregue su salida.

Si Claude inicia un subagente en segundo plano o flujo de trabajo, claude -p en su lugar permanece abierto hasta que ese trabajo se complete, porque su resultado es parte de la salida final.

De forma predeterminada, la espera termina después de 10 minutos de espera inactiva continua, por lo que un subagente o flujo de trabajo atascado no puede mantener el proceso abierto indefinidamente. En ese punto, Claude Code detiene lo que aún se está ejecutando y descarta su resultado parcial. Para cambiar el límite, establezca CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS, o establézcalo en 0 para esperar sin uno.

Si Claude inicia una vigilancia de Monitor durante una ejecución de claude -p, Claude Code espera la vigilancia hasta que se agote el tiempo de espera o el límite de diez minutos termine la espera, lo que ocurra primero. Mientras espera, Claude continúa respondiendo a lo que la vigilancia reporta. De forma predeterminada, una vigilancia se agota cinco minutos después de que Claude la inicia.

Detener una ejecución con SIGTERM

Si detiene una ejecución de 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íe SIGINT, o llame 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 los hooks SessionEnd y sale. Al salir, Claude Code no inicia ninguna nueva llamada de herramienta, no envía ninguna nueva solicitud de modelo y no ejecuta ningún hook que no sea SessionEnd. Si la ejecución estaba en medio de un comando o esperando una respuesta a 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 eliminado en la sesión.
• Esperando una respuesta a una solicitud de permiso: si envía SIGTERM al proceso, Claude Code deja la solicitud sin responder. Si su programa cierra la sesión a través del Agent SDK, el SDK termina la entrada de Claude Code antes de enviar cualquier señal, y Claude Code cancela la solicitud tan pronto como la entrada termina.

Cuando reanuda la sesión, Claude Code continúa el turno que SIGTERM dejó sin terminar.

Ejemplos

Estos ejemplos destacan patrones comunes de CLI. Donde un comando nombra un archivo como auth.py o build-error.txt, sustituya un archivo de su propio proyecto. En CI u otros entornos con scripts, agregue --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 puede 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 por invocación sin consultar el panel de uso. Ambas cifras son estimaciones del lado del cliente y pueden diferir de su factura real.

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 indicador de la línea de comandos. Antes de v2.1.211, un stdin no legible en Windows bloqueaba la sesión o hacía que saliera silenciosamente sin salida.

Agregar Claude a un script de compilación

Puede 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.\""
  }
}

Ejecute con npm run lint:claude.

Obtener salida estructurada

Utilice --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 transmisión 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, utilice --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. Antes de v2.1.205, Claude Code ignoraba silenciosamente un esquema inválido y devolvía texto no estructurado, y trataba cualquier esquema que contenía format como inválido.

Transmitir respuestas

Utilice --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 de la transmisión es un mensaje result con el texto de respuesta final, el costo y los metadatos de la sesión.

Si su consumidor lee la transmisión lentamente, Claude Code espera a que se drene la salida en cola antes de salir, escalando la espera con cuánto aún está en cola, limitado a 30 segundos. Antes de v2.1.214, la espera de salida estaba limitada a aproximadamente dos segundos, lo que podría cortar el final de una respuesta grande.

El siguiente ejemplo utiliza jq para filtrar deltas de texto y mostrar solo el texto transmitido. La bandera -r genera cadenas sin formato (sin comillas) y -j se une sin saltos de línea para que los tokens se transmitan continuamente:

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 transmisión programática con devoluciones de llamada y objetos de mensaje, consulte Transmitir respuestas en tiempo real en la documentación del Agent SDK.

Seguir mensajes de subagentes

Los mensajes de subagentes aparecen en la transmisión como mensajes assistant y user cuyo campo parent_tool_use_id es el ID de la llamada de herramienta que generó el subagente. Los mensajes de la conversación principal llevan null en ese campo.

El primer mensaje de un subagente que se ejecuta en primer plano es un mensaje user que lleva el indicador que lo impulsa. Después de ese primer mensaje, Claude Code emite:

• De forma predeterminada: los bloques tool_use y tool_result del subagente.
• Con --forward-subagent-text o CLAUDE_CODE_FORWARD_SUBAGENT_TEXT: también los bloques de texto y pensamiento del subagente, para que pueda reconstruir la transcripción de cada subagente. Esto requiere Claude Code v2.1.211 o posterior.

Cuando habilita cualquiera de las opciones, Claude Code reenvía mensajes de subagentes en cada profundidad de anidamiento: cuando un subagente genera su propio subagente, los mensajes del subagente anidado llevan el ID de la llamada de herramienta Agent que lo generó en parent_tool_use_id, para que pueda reconstruir el árbol de anidamiento completo siguiendo esos IDs. Antes de v2.1.219, los mensajes de subagentes anidados no aparecían en la transmisión.

Las skills que se ejecutan en un subagente aparecen en la transmisión de la misma manera: el primer mensaje de la skill bifurcada es un mensaje user que lleva el contenido de la skill que impulsa la ejecución. Si habilita cualquiera de las opciones, la transmisión también lleva los bloques de texto y pensamiento de la skill bifurcada. Antes de v2.1.265, solo los bloques tool_use y tool_result de una skill bifurcada aparecían en la transmisión.

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 hacia attempt. Puede usar el evento para mostrar el progreso del reintento en su propia interfaz.

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 la transmisión 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 a medida que el hook los produce. Claude Code v2.1.169 a v2.1.203 los entregó en un lote después de que el hook se completó, aún antes de system/init; v2.1.204 restauró la entrega en vivo.

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. Verifíquelo para detectar características en lugar de comparar cadenas de versión, e ignore valores que no reconozca. El campo requiere Claude Code v2.1.205 o posterior y está ausente en versiones anteriores. Consulte SDKSystemMessage para la lista de capacidades.

Fallar CI cuando un plugin o servidor MCP no se carga

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

Utilice los campos del servidor MCP de la misma manera. Cuando pasa --mcp-config con -p, Claude Code espera a que los servidores aún pendientes se completen 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 de herramienta. La espera requiere Claude Code v2.1.221 o posterior.

Claude Code valida cada entrada --mcp-config al inicio y omite las entradas que fallan la validación, por ejemplo una entrada url sin type. La ejecución continúa y sale limpiamente, por lo que verifique estos campos para detectar un servidor que nunca se cargó:

Cuando ejecuta 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 para cada entrada omitida. Cuando redirige stderr, o cuando un programa como un ejecutor de CI o un host SDK lo captura, Claude Code no imprime advertencia e informa las entradas omitidas solo en el campo mcp_server_errors. La advertencia requiere Claude Code v2.1.219 o posterior.

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. Use estos para mostrar el progreso de instalación en su propia interfaz de usuario.

Aprobar herramientas automáticamente

Utilice --allowedTools para permitir que Claude use ciertas herramientas sin solicitar confirmación. Este ejemplo ejecuta un conjunto de pruebas y corrige fallos, permitiendo que Claude ejecute comandos Bash y lea/edite archivos sin pedir permiso:

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

Para establecer una línea base para toda la sesión en lugar de enumerar herramientas individuales, pase un modo de permiso. Para -p, el modo de permiso de inicio integrado es Manual en cada plan, por lo que pase el modo de permiso que desee:

• auto: pase --permission-mode auto para que un clasificador revise la mayoría de las acciones en lugar de usted
• dontAsk: Claude Code deniega cualquier llamada que de otro modo solicitaría, lo que es útil para ejecuciones de CI bloqueadas. Las acciones que no necesitan aprobación en modo Manual aún se ejecutan, como lecturas de archivos en sus directorios de trabajo y el conjunto de comandos de solo lectura, y también lo hacen las acciones que sus entradas --allowedTools o reglas permissions.allow cubren. AskUserQuestion, herramientas de conector que su organización configuró para ask, y herramientas MCP marcadas requiresUserInteraction se deniegan incluso cuando una regla de permiso coincide
• acceptEdits: Claude escribe archivos sin solicitar, 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. Consulte qué acceptEdits aprueba automáticamente 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 indicadores de permiso en ejecuciones desatendidas

Pase --permission-prompts none cuando nadie esté disponible para responder indicadores de permiso, por ejemplo en un trabajo programado. La bandera es más importante cuando su ejecución tiene un host de permiso: una aplicación Agent SDK con una devolución de llamada canUseTool, o una herramienta MCP que pasa con --permission-prompt-tool. Sin la bandera, su ejecución espera a que ese host responda cada solicitud de permiso.

Con la bandera, su ejecución no consulta al host ni espera en él. Cualquier cosa que solicitaría se deniega a menos que un hook PermissionRequest lo permita, se le dice 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 la bandera también le dice a Claude que no las reintente. Las reglas de permiso, hooks PermissionRequest, y el modo de permiso que establezca aún deciden cada llamada primero; 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 recurrido a un indicador:

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.

Crear una confirmación

Este ejemplo revisa los cambios preparados y crea una confirmación 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 *)"

La bandera --allowedTools utiliza sintaxis de regla de permiso. 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.

Personalizar el indicador del sistema

Utilice --append-system-prompt para agregar instrucciones mientras mantiene el comportamiento predeterminado de Claude Code. Este ejemplo canaliza un diff de PR a Claude e le indica que revise las vulnerabilidades de seguridad. Guárdelo 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 pasa en la línea de comandos. Ejecute bash review.sh 123 y el shell reemplaza "$1" con 123, por lo que el script obtiene el diff para PR 123. Claude Code imprime la revisión como JSON, con el texto en el campo result.

Consulte banderas de indicador del sistema para más opciones incluyendo --system-prompt para reemplazar completamente el indicador predeterminado.

Continuar conversaciones

Utilice --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 pasa --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 indicaciones 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á ejecutando múltiples conversaciones, capture 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"

Puede ejecutar los dos comandos desde diferentes directorios: Claude Code encuentra la sesión por su ID en cualquier proyecto en esta máquina. Antes de v2.1.223, Claude Code buscaba el ID solo en el directorio del proyecto actual y sus git worktrees, por lo que tenía que ejecutar ambos comandos desde el mismo directorio.

En lugar del ID de sesión, puede 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