Modo headless y Agent SDK

Corre Claude automáticamente en scripts y pipelines de CI/CD

⏱ Estim. ~6 min

01 · Leer

Hasta ahora todo lo que has hecho con Claude Code ha sido interactivo: tú escribes, Claude responde, tú apruebas. ¿Pero qué pasa si quieres que Claude corra automáticamente? ¿En un pipeline de CI/CD que revise cada pull request? ¿En un script que arregle errores de lint cada noche?

El modo headless (claude -p) corre Claude sin terminal interactiva. Le das un prompt, hace el trabajo y devuelve resultados. Sin teclear, sin diálogos de aprobación, solo entrada y salida.

Así integran los equipos a Claude en flujos automatizados: bots de code review, fixers de tests, generadores de documentación y mucho más.

💡 Imagínalo asíClaude interactivo es como tener una conversación con un colega sentado a tu lado. Claude headless es como mandarle una tarea por email: envías la solicitud, la hace y te llega el resultado de vuelta. Sin idas y vueltas.

Puntos clave

claude -p corre Claude de forma no interactiva (modo headless)
Perfecto para scripts, pipelines de CI/CD y automatización
Sin diálogos de aprobación: especifica las herramientas permitidas de antemano
La salida puede ser texto, JSON o JSON en streaming

02 · Ejemplo de código

Estos son patrones comunes del modo headless. La bandera -p lo hace no interactivo.

Uso básico de headless

# Simple query
claude -p "Find all TODO comments in this project"

# With allowed tools (auto-approved, no prompts)
claude -p "Run tests and fix failures" \
  --allowedTools "Bash(npm test*),Read,Edit"

# Structured JSON output
claude -p "List all API endpoints" \
  --output-format json

La bandera -p (de 'print') corre Claude de forma no interactiva. --allowedTools preaprueba herramientas específicas para que Claude pueda trabajar sin prompts de permiso. --output-format json devuelve datos estructurados en vez de texto plano, útil cuando otros programas necesitan parsear el resultado.

03 · Ejemplo de código

Así usan los equipos el modo headless en pipelines de CI/CD: un code reviewer automatizado que corre en cada pull request.

GitHub Actions: code review automatizado

# .github/workflows/claude-review.yml
name: Claude Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Review PR
        run: |
          claude -p "Review the changes in this PR. \
            Focus on bugs, security, and performance." \
            --allowedTools "Read,Grep,Glob" \
            --output-format text

Esta GitHub Action corre Claude en modo headless en cada pull request. Solo permite herramientas de solo lectura (Read, Grep, Glob), así que Claude puede analizar el código pero no cambiar nada. La salida del review aparece en el log de CI para que el equipo la lea.

04 · Leer

Para automatizaciones más sofisticadas, Anthropic ofrece el Agent SDK: librerías de Python y TypeScript con soporte de las herramientas de Claude para construir agentes de producción.

El Agent SDK te da control programático sobre todo: qué herramientas están disponibles, cómo se manejan los resultados, manejo de sesión (continuar conversaciones) e incluso conexiones a servidores MCP. Es lo que impulsa las integraciones más sofisticadas con Claude Code.

La CLI (claude -p) es buena para automatización simple. El Agent SDK es para cuando necesitas control programático completo: manejo de errores a medida, streaming de resultados, encadenar varias llamadas a Claude o construir un producto sobre las capacidades de Claude.

Puntos clave

Agent SDK: librerías Python y TypeScript para agentes de producción
Control programático completo sobre herramientas, sesiones y resultados
CLI (claude -p): automatización simple y scripts
Agent SDK: aplicaciones sofisticadas y sistemas de producción
Manejo de sesión: captura y continúa conversaciones por código

05 · Ejemplo de código

Este es un ejemplo simple del Agent SDK en TypeScript que encuentra y arregla bugs por código.

Agent SDK: bug fixer

import { query } from '@anthropic-ai/claude-agent-sdk';

for await (const msg of query({
  prompt: "Find and fix the failing test in auth.test.ts",
  options: {
    allowedTools: ["Read", "Edit", "Bash"],
  }
})) {
  if (msg.result) {
    console.log('Fix applied:', msg.result);
  }
}

El Agent SDK te da una interfaz de streaming: iteras sobre los mensajes mientras Claude trabaja. El array allowedTools controla lo que Claude puede hacer. Cuando Claude termina, el mensaje result contiene un resumen de lo que hizo. Así construyes agentes automatizados que pueden leer, editar y correr comandos.

06 · Quiz

¿Qué bandera hace que Claude Code corra de forma no interactiva, sin terminal interactiva?

claude --headless
claude --auto
claude -p
claude --batch

07 · Completar

Para correr Claude en un pipeline de CI/CD sin interacción del usuario, usa claude _____ "tu prompt".

08 · Emparejar

Empareja cada enfoque de automatización con su mejor caso de uso.

(Esta sección es interactiva — activa JavaScript para usarla.)

Otras lecciones de este capítulo

⚠ La experiencia interactiva completa necesita JavaScript. Actívalo y vuelve a cargar la página.

※ Este es un proyecto educativo independiente — no es un producto oficial de Anthropic. Claude™ es una marca registrada de Anthropic, PBC.