Claude Code headless: scripts por lotes con claude -p
Claude Code headless con claude -p: bucles bash y Bun para migrar archivos, crear changelogs y clasificar issues con JSON validado y el coste bajo control.

Tienes 140 archivos de test en Jasmine y el equipo ha decidido pasar a Vitest. Abres Claude Code, le pides que migre el primero, revisas, aceptas. Segundo archivo. Tercero.
En el archivo veinte ya no lees los diffs. En el cuarenta, el contexto de la sesión arrastra los treinta y nueve anteriores y las respuestas empiezan a mezclar convenciones. Estás usando Claude Code en modo interactivo para un trabajo que pide Claude Code headless.
Ese trabajo tiene forma de bucle: el mismo prompt, N entradas, una salida que puedes comprobar. La herramienta es la misma que usas en la terminal, pero llamada desde un script con claude -p.
En corto: claude -p ejecuta Claude Code sin interfaz: recibe un prompt, hace el trabajo, imprime el resultado y sale con un código de salida. Para lotes, llámalo una vez por archivo con --bare, herramientas acotadas y --max-budget-usd, y usa --json-schema si otro programa va a leer la salida. Si necesitas decidir en código qué se aprueba en cada llamada, pasa al Agent SDK.
¿Qué es Claude Code headless?
Claude Code headless es el modo no interactivo de Claude Code: con el flag -p (o --print) se ejecuta una tarea completa desde la línea de comandos, sin sesión abierta, y el resultado sale por stdout como texto o JSON.
La documentación oficial de modo headless (consultada el 10 de octubre de 2026) lo presenta como el Agent SDK usado desde la CLI. Lee stdin, así que encaja en tuberías, y devuelve 0 si la ejecución va bien y un código distinto si falla. Tu script puede ramificar sobre eso como con cualquier otro comando.
Flags de Claude Code headless que importan en un script
De la referencia de la CLI, estos son los flags que cambian el resultado de un lote:
| Flag | Qué hace | Por qué importa en un lote |
|---|---|---|
--bare |
Omite hooks, skills, plugins, MCP, auto memory y CLAUDE.md |
Mismo resultado en cualquier máquina. La doc dice que será el valor por defecto de -p |
--tools "Read,Edit" |
Restringe las herramientas disponibles | Lo que no está en la lista no existe para el modelo |
--allowedTools |
Aprueba sin preguntar las herramientas o reglas indicadas | Acepta reglas como Edit(./src/a.ts) o Bash(git diff *) |
--permission-mode dontAsk |
Deniega todo lo que pediría confirmación | Nadie va a contestar un prompt a las tres de la mañana |
--max-turns 8 |
Corta tras N turnos agénticos y sale con error | Evita que un archivo raro se convierta en un bucle largo |
--max-budget-usd 0.50 |
Para la ejecución al llegar a ese gasto estimado | Pone techo al coste de cada llamada |
--output-format json |
Devuelve result, session_id, total_cost_usd y metadatos |
El script puede leer coste y errores con jq |
--json-schema '<schema>' |
Valida la salida contra un JSON Schema | El resultado llega en el campo structured_output |
Ojo: --allowedTools aprueba, no restringe. Para limitar qué herramientas existen, la referencia manda a --tools. En el issue #33343 de claude-code, un usuario lanzó claude -p con --permission-mode bypassPermissions y --allowedTools "Glob", y Claude leyó igualmente el archivo que no debía. Con bypassPermissions no hay nada que aprobar, así que la lista no protegía nada. Dónde poner cada barrera lo cuento en hooks vs permissions en Claude Code.
La regla: en desatendido, --tools define qué existe, --allowedTools qué se aprueba y dontAsk deniega lo que pediría confirmación (las lecturas dentro del directorio de trabajo y los comandos de solo lectura siguen pasando). Nunca uses bypassPermissions en un bucle.
Migrar N archivos con un bucle de Claude Code headless
La clave de Claude Code headless en un lote es una llamada por archivo: contexto limpio, fallo aislado y un log por ejecución.
#!/usr/bin/env bash
# migrate-vitest.sh: migra cada spec de Jasmine a Vitest en una llamada aislada
set -uo pipefail
mkdir -p .migracion
git ls-files 39;*.spec.ts39; | while IFS= read -r file; do
log=".migracion/$(echo "$file" | tr '/' '_').json"
claude --bare -p "Migra $file de Jasmine a Vitest. Edita solo ese archivo." \
--append-system-prompt-file ./docs/migracion-vitest.md \
--tools "Read,Edit" \
--allowedTools "Read,Edit(./$file)" \
--permission-mode dontAsk \
--max-turns 8 \
--max-budget-usd 0.50 \
--output-format json < /dev/null > "$log"
if npx vitest run "$file" < /dev/null > /dev/null 2>&1; then
echo "OK $file $(jq -r '.total_cost_usd' "$log") USD"
else
git checkout -- "$file"
echo "MAL $file (revertido, revisar a mano)"
fi
done
Tres detalles que no son decoración:
< /dev/null.claude -plee stdin. Dentro de unwhile read, sin esa redirección, la primera llamada se come la lista de archivos que queda en la tubería y el bucle termina tras una vuelta.Edit(./$file). La regla aprueba editar ese archivo y ningún otro. CondontAsk, cualquier intento de tocar otro archivo se deniega.--append-system-prompt-file.--bareno lee tuCLAUDE.md, así que las convenciones de la migración van en un archivo que pasas a mano.
La regla: el script verifica, no el modelo. Que Claude diga "migrado" no vale nada; que vitest run pase sí.
Generar un changelog con claude -p
No todo lote necesita herramientas. Un changelog es texto que entra por stdin y texto que sale por stdout:
git log --no-merges --pretty=format:39;%h %s39; v2.3.0..HEAD |
claude --bare -p "Agrupa estos commits en un changelog en markdown con las secciones Añadido, Cambiado y Corregido. Devuelve solo el markdown." \
--tools "" \
--max-budget-usd 0.20 > CHANGELOG-next.md
--tools "" desactiva todas las herramientas: Claude solo ve lo que le pasas. Es el uso más seguro de Claude Code no interactivo.
Clasificar issues con salida JSON y schema
Cuando el resultado lo va a consumir otro programa, el texto libre no sirve. --json-schema necesita --output-format json, y la salida validada aparece en structured_output:
SCHEMA=39;{"type":"object","properties":{"label":{"type":"string","enum":["bug","enhancement","question","documentation"]},"priority":{"type":"string","enum":["p0","p1","p2"]},"reason":{"type":"string"}},"required":["label","priority","reason"],"additionalProperties":false}39;
gh issue list --state open --limit 30 --json number,title,body |
jq -c 39;.[]39; |
while IFS= read -r issue; do
number=$(jq -r 39;.number39; <<< "$issue")
out=$(jq -r 39;.title + "\n\n" + (.body // "")' <<< "$issue" |
claude --bare -p "Clasifica esta issue de GitHub. En reason, explica el motivo en una frase." \
--permission-mode dontAsk \
--output-format json \
--json-schema "$SCHEMA" \
--max-budget-usd 0.10)
label=$(jq -r 39;select(.is_error == false) | .structured_output.label // empty' <<< "$out")
if [ -z "$label" ]; then
echo "#$number sin clasificar"
continue
fi
gh issue edit "$number" --add-label "$label"
echo "#$number -> $label"
done
Aquí claude lee de su propia tubería, así que no hace falta < /dev/null. Los enum impiden que el modelo invente una etiqueta. Las cuatro del ejemplo vienen por defecto en GitHub; si usas otras, créalas antes con gh label create.
Validar el structured_output con Zod en un script Bun
Un schema válido no garantiza un resultado útil. En el issue #77026 de claude-code, abierto en julio de 2026, varios usuarios reportan que con claude -p --json-schema la ejecución devuelve subtype: "success" con datos rotos. El fallo más frecuente es que el modelo mete marcado XML del tool-call dentro de un campo string; otras veces rellena el campo con "placeholder" o "test" para pasar la validación. Un colaborador de Anthropic no lo reprodujo en 6 ejecuciones con la v2.1.233, y otro usuario lo confirmó después en la v2.1.237 con Sonnet 5. Raro, pero en un lote de miles, pasa.
La defensa es validar otra vez en tu lado con una regla que el schema no puede expresar. Con Zod, el mismo objeto genera el JSON Schema y valida el resultado, el patrón de cómo tipar las respuestas de una LLM con Zod. El truco está en el refine: toJSONSchema lo ignora, así que no llega al CLI y solo lo comprueba tu script.
// triage.ts: bun run triage.ts
import { z } from "zod";
const Triage = z.object({
label: z.enum(["bug", "enhancement", "question", "documentation"]),
priority: z.enum(["p0", "p1", "p2"]),
reason: z
.string()
.min(20)
// toJSONSchema ignora el refine: esta regla solo se aplica en tu lado
.refine((s) => !/placeholder|<\/?[a-z]/i.test(s), "reason con relleno o marcado XML"),
});
const RunResult = z.object({
is_error: z.boolean(),
total_cost_usd: z.number(),
structured_output: z.unknown(),
});
const schema = JSON.stringify(z.toJSONSchema(Triage, { target: "draft-7" }));
const BATCH_LIMIT_USD = 3;
async function runClaude(text: string) {
const proc = Bun.spawn(
[
"claude", "--bare", "-p", "Clasifica esta issue de GitHub.",
"--permission-mode", "dontAsk",
"--output-format", "json",
"--json-schema", schema,
"--max-budget-usd", "0.10",
],
{ stdin: new Blob([text]) },
);
const stdout = await proc.stdout.text();
await proc.exited;
return RunResult.parse(JSON.parse(stdout));
}
type Issue = { number: number; title: string; body: string };
const issues: Issue[] =
await Bun.$`gh issue list --state open --limit 30 --json number,title,body`.json();
let spent = 0;
for (const issue of issues) {
if (spent >= BATCH_LIMIT_USD) {
console.error(`Tope del lote alcanzado: ${spent.toFixed(2)} USD`);
break;
}
try {
const run = await runClaude(`${issue.title}\n\n${issue.body}`);
spent += run.total_cost_usd;
const triage = Triage.safeParse(run.structured_output);
if (run.is_error || !triage.success) {
console.error(`#${issue.number} sin clasificar`);
continue;
}
console.log(`#${issue.number} ${triage.data.label}/${triage.data.priority}`);
} catch (error) {
console.error(`#${issue.number} falló: ${error}`);
}
}
El target: "draft-7" no es opcional: la documentación de structured outputs indica que el validador usa JSON Schema draft-07 y que Zod genera 2020-12 por defecto. Desde Claude Code v2.1.205, un schema inválido hace fallar la ejecución al arrancar; antes se ignoraba en silencio. Y el JSON se parsea aunque el código de salida no sea 0, porque los fallos internos salen como resultado en stdout.
safeParse, refinamientos y transformaciones están en el curso de Zod.
Interactivo, claude -p o Agent SDK: cuándo usar cada uno
| Criterio | Sesión interactiva | claude -p (headless) |
Agent SDK (TS / Python) |
|---|---|---|---|
| Quién aprueba permisos | Tú, en cada prompt | Reglas fijas antes de arrancar | Tu código, llamada a llamada (canUseTool) |
| Salida | Conversación | Texto, JSON o stream-json |
Objetos de mensaje nativos |
| Unidad de trabajo | Una tarea abierta | Un comando, una entrada | Un programa con estado |
| Encaja en | Diseño, depuración, exploración | Bucles bash, CI, cron, package.json |
Productos y servicios con agentes |
| Control de coste | Lo ves en la sesión | --max-budget-usd por llamada |
Presupuesto y lógica propia |
| Riesgo principal | Aprobar diffs sin leerlos por cansancio | Permisos amplios sin nadie mirando | Más código que mantener y testear |
La regla: quédate en claude -p mientras el script quepa en una pantalla y los permisos sean estáticos. Si necesitas aprobar según el contenido de cada llamada, reintentar con lógica propia o guardar estado, pasa al SDK. El siguiente paso está en servidor de herramientas para tu agente con el SDK de Anthropic.
Límites de Claude Code headless en tareas por lotes
El coste escala con N. --max-budget-usd limita cada llamada, no el lote, y es una estimación del cliente que el gasto puede superar. Por eso el script Bun lleva su propio contador. En el issue #37686, un usuario con plan Max cuenta que sus scripts programados con claude -p heredaron una ANTHROPIC_API_KEY de su shell y facturaron más de 1.800 USD en dos días a una cuenta de API.
No es determinista. El mismo prompt sobre el mismo archivo puede dar dos migraciones distintas. Sin verificación automática (tests, tipos, lint), un lote multiplica la incertidumbre.
Permisos amplios en desatendido. --allowedTools "Bash" en un bucle equivale a ejecutar lo que el modelo decida, N veces, sin nadie delante. Acota con reglas como Bash(git diff *) o no des Bash.
--bare ignora tu CLAUDE.md. Por eso es reproducible y por eso olvida tus convenciones, hooks y servidores MCP. Lo que el modelo necesite va en --append-system-prompt, --settings o --mcp-config.
Cómo empezar con Claude Code headless en tus scripts
Elige una tarea repetitiva que ya verifiques con un comando: un test, tsc --noEmit o un linter. Escribe el bucle de Claude Code headless con --bare, --tools mínimo, dontAsk y tope de presupuesto, y lánzalo sobre tres archivos antes que sobre trescientos.
Ese prompt fijo que repites en el bucle es, en el fondo, una especificación pequeña. Es la misma idea del libro Spec-Driven Development: cuanto más precisa la entrada, menos tienes que revisar a la salida. Y si quieres el flujo completo de idea a producto con Claude Code, está en el curso Construye con IA.
Para revisar cada PR, mira revisiones de código con IA en tu pipeline de CI/CD; para un flujo visual sin scripts, Claude Code con n8n.
Preguntas frecuentes
¿Qué diferencia hay entre –allowedTools y –tools en claude -p?
--tools restringe qué herramientas existen en la sesión. --allowedTools aprueba sin preguntar las que indiques, pero no elimina las demás. En scripts desatendidos, combina los dos con --permission-mode dontAsk.
¿–max-budget-usd limita el coste total del lote?
No. Limita cada ejecución de claude -p por separado. Para un tope del lote, suma total_cost_usd de cada respuesta JSON y corta el bucle al llegar al límite.
¿Cómo saco el structured_output de claude -p con jq?
Ejecuta claude -p con --output-format json y --json-schema, y filtra con jq '.structured_output'.
¿Claude Code headless usa mi suscripción o la API de Anthropic?
Depende. Sin --bare, claude -p usa tu login de claude.ai, salvo que tengas ANTHROPIC_API_KEY en el entorno: en modo -p la clave se usa siempre que exista, sin preguntar. Con --bare, Claude Code no lee tu login: necesitas ANTHROPIC_API_KEY o un apiKeyHelper en --settings, y pagas por token. Antes de un lote, ejecuta claude auth status y mira el campo authMethod.
¿Cuándo pasar de claude -p al Agent SDK?
Cuando aprobar una herramienta depende del contenido de cada llamada, cuando necesitas reintentos o estado entre pasos, o cuando el agente forma parte de un producto. El SDK da callbacks de permisos y mensajes nativos; claude -p, un comando que cabe en un bucle bash.
Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.
¿Quieres construir con agentes en serio?
Curso «Construye con IA» con Claude Code, de la idea al producto.
Developer con más de 15 años en frontend y creador de Dominicode. Escribe sobre IA aplicada al desarrollo de software.
¿Te resultó útil este artículo?
Compártelo con tu comunidad y ayuda a otros desarrolladores.