Headless y scripting

Toda la automatización de este curso se apoya en una idea: Claude Code se puede ejecutar sin interfaz interactiva, como un comando más de Unix. Eso es el modo headless, y se activa con -p.

claude -p: el modo no interactivo

Añade -p (o --print) a cualquier invocación de claude para que ejecute la tarea, imprima la respuesta y termine:

claude -p "¿Qué hace el módulo de auth?"

Sin sesión interactiva, sin esperar input. Perfecto para scripts y CI.

Filosofía Unix: pipes

Como cualquier comando, lee de stdin y escribe a stdout, así que se compone con otras herramientas. Mete datos por una tubería y redirige la salida:

cat build-error.txt | claude -p "explica la causa raíz de este error de build" > causa.txt

O úsalo como linter del proyecto, sobre el diff contra main:

git diff main | claude -p "eres un linter de typos. Por cada typo en este diff, di fichero:línea y el problema. Nada más."

Pasar el diff por pipe tiene una ventaja sutil: Claude no necesita permiso de Bash para leerlo, porque ya le llega por stdin. Menos permisos que conceder.

Puedes envolverlo en un script de package.json y tenerlo como un comando más:

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"reporta typos en este diff, formato fichero:línea\""
  }
}

Modo bare: reproducible en CI

En tu máquina, claude -p carga el mismo contexto que una sesión interactiva: tus hooks, skills, MCP, CLAUDE.md… En CI eso es un problema: quieres el mismo resultado en cada máquina, no que dependa de lo que alguien tenga en su ~/.claude. Para eso, --bare:

claude --bare -p "Resume este fichero" --allowedTools "Read"

--bare se salta el autodescubrimiento de hooks, skills, plugins, MCP y CLAUDE.md: solo aplica lo que le pasas explícitamente por flags. Es el modo recomendado para scripts y CI.

En --bare, Claude tiene Bash, lectura y edición de ficheros. Lo demás (system prompt, settings, MCP, agentes) se lo pasas con flags: --append-system-prompt, --settings, --mcp-config, --agents.

Un apunte sobre coste

El modo headless / SDK consume como cualquier uso. A partir de mediados de junio de 2026, en planes de subscripción claude -p pasa a usar un crédito mensual de Agent SDK separado del uso interactivo; tenlo en cuenta al automatizar trabajo recurrente.

Qué llevas hasta aquí

• claude -p ejecuta Claude sin interfaz: ideal para scripts y CI.
• Se compone como Unix: pipes de stdin, redirección de stdout, scripts de package.json.
• --bare lo hace reproducible en CI al no cargar config local; pasas lo que necesites por flags.

En la siguiente lección, controlar su salida y sus permisos para que corra solo, sin nadie que apruebe nada.

Fuente oficial: Run Claude Code programmatically · CLI reference