Gonzalo Gomez
Claude Code en modo headless: tu agente conversacional sin costo de API
Guía del modo headless de Claude Code como motor de tu agente conversacional: wrapper en Python, sesiones con --resume, streaming y cuándo migrar al API.
Introducción
Cada prueba que hacés contra el API de Anthropic mientras desarrollás un agente conversacional te cuesta plata. Ajustás el system prompt, mandás 40 mensajes de prueba, algo no te cierra, volvés a ajustar, otros 40 mensajes. Todo eso es facturación por tokens antes de tener un solo usuario real.
Si tenés suscripción de Claude (Pro o Max), hay una alternativa que casi nadie usa para esto: el modo headless de Claude Code. Le pasás el prompt y el mensaje del usuario, te devuelve la respuesta en texto plano, y el consumo sale de tu suscripción, no del API. Este PDF es la implementación de principio a fin, con los casos de uso donde tiene sentido y el límite donde deja de tenerlo.
Qué vas a encontrar en este PDF
El comando base para un agente: salida estructurada con --output-format json, tu system prompt con --append-system-prompt y control de herramientas con --allowedTools.
La implementación completa con Python: el wrapper que invoca claude -p y el endpoint que recibe el webhook de tu canal, sea WhatsApp o un chat web.
Cómo mantener el hilo de la conversación con --resume y el mapeo de usuario a session_id, sin armar el historial a mano.
Streaming con stream-json para mostrar la respuesta a medida que se genera.
Los casos de uso donde brilla: iterar el system prompt sin que el medidor del API se mueva, suites de regresión de prompts, demos a clientes y prototipos internos.
El límite, que es importante: por qué esto es para desarrollo y pruebas locales, y cuándo corresponde migrar al API con el Anthropic SDK.
Para quién es
Para desarrolladores que están armando un agente conversacional y queman la mayor parte de sus requests justo en la etapa donde el agente todavía no funciona. El modo headless te saca el costo de esa etapa. La etapa donde el agente ya funciona es la que tiene que pagar su propio API.
Descargá el PDF con el botón de arriba y tenés el comando, el código y los flags en tres páginas, listos para adaptar a tu proyecto.
