Cómo reducir tokens en Claude Code con hooks y Portal de Spotify

Claude Code
, , , , , ,
1

Spotify mostró una forma concreta de reducir el uso de tokens en Claude Code: bloquear lecturas grandes con hooks y delegar trabajo predecible a modos de Portal.

La cifra llamativa es el 90% de ahorro que Spotify reporta en su propio benchmark. Conviene leerla con cuidado: es una medición de Spotify sobre un monorepo Java, no una garantía universal. La idea más duradera es otra: si un agente de código gasta tokens de un modelo fuerte leyendo archivos enormes o generando código predecible, no basta con pedirle que sea disciplinado. Puedes mover esa decisión al borde de las herramientas.

En ese patrón, Claude Code conserva el razonamiento, la depuración, la edición y las decisiones delicadas. Portal se encarga de lecturas masivas y generación rutinaria mediante modos de AiKA respaldados por modelos de trabajo más baratos.

¿Cómo reduce Spotify tokens en Claude Code?

Spotify reduce tokens en Claude Code con un plugin llamado shunt, que intercepta lecturas grandes, las bloquea y le indica a Claude que use scripts respaldados por Portal.

El patrón tiene tres piezas:

  • Hooks que deciden cuándo Claude Code no debería leer algo directamente.
  • Scripts que invocan modos de AiKA en Portal con argumentos definidos.
  • Skills que le explican a Claude cuándo y cómo usar esos scripts.

La diferencia frente a una regla escrita en CLAUDE.md es importante. Una instrucción en texto es una recomendación. Claude puede seguirla, olvidarla o rodearla. Un hook PreToolUse, en cambio, corre antes de la llamada a la herramienta y puede detener la operación costosa antes de que el contexto llegue al modelo principal.

El movimiento útil es simple: no uses el modelo más fuerte para descubrir qué parte de cinco archivos gigantes importa. Usa un worker para hacer la primera lectura, recibe un resumen estructurado y deja que Claude inspeccione después las líneas específicas que sí requieren juicio.

¿Qué es Portal de Spotify?

Portal de Spotify es el portal de desarrollo gestionado de Spotify, construido sobre Backstage, con capacidades de IA como modos de AiKA para asistentes especializados.

En la documentación de Portal, un modo es una configuración declarativa de agente. Puede definir instrucciones, visibilidad, modelo, herramientas MCP, límites de recursos y procesadores como planificación, verificación, scoring de confianza y manejo de contexto.

Eso importa porque el worker de este patrón no es solamente “otro prompt”. Es un modo reutilizable que una organización puede compartir, invocar desde Portal y mover a otro modelo configurado sin reescribir el plugin de Claude Code.

Spotify usa dos modos como ejemplo:

  • bulk-reader, para leer varios archivos grandes y devolver hallazgos concisos.
  • code-writer, para producir código predecible como tests, stubs de tipos o scaffolding de configuración a partir de una referencia.

En el ejemplo publicado, Spotify usa Gemini 2.5 Flash como modelo barato para esos modos. La documentación también deja claro que el modelo puede cambiar según lo que esté configurado en la instancia de Portal. Ese es el punto: el modelo caro no tiene por qué ser el destino por defecto de cada tarea solo porque está manejando la sesión.

¿Cómo funciona el plugin shunt para Claude Code?

El plugin shunt funciona registrando hooks de Claude Code que bloquean lecturas grandes y redirigen a Claude hacia scripts especializados.

Según el README enlazado por el artículo de Spotify, shunt registra dos hooks orientados a lectura:

  • check-file-size, que corre sobre llamadas Read y bloquea lecturas completas por encima de un umbral de líneas.
  • check-bash-read, que detecta lecturas grandes hechas con comandos como cat, head, tail, less y more.

El umbral por defecto es 350 líneas. Las lecturas con offset o limit pasan, porque si Claude pide una sección concreta, probablemente ya sabe qué parte necesita. Las lecturas con pipes como cat archivo | grep también pasan porque son consultas acotadas, no volcados crudos de contexto.

El umbral puede ajustarse con SHUNT_MIN_LINES en .claude/settings.json:

{
  "env": {
    "SHUNT_MIN_LINES": "500"
  }
}

Ese detalle muestra por qué esto es más que higiene de prompts. Claude todavía puede leer código. Todavía puede inspeccionar secciones exactas. Lo que el hook bloquea es el patrón caro: meter un archivo grande completo en el modelo principal “por si acaso”.

¿Cómo se instala Portal de Spotify en Claude Code?

Al momento de publicar esta nota, 6 de septiembre de 2026, Spotify muestra una instalación desde el marketplace spotify/portal-ai-plugins y después una configuración de Portal dentro de una nueva sesión de Claude Code.

Los comandos publicados por Spotify son:

claude plugin marketplace add spotify/portal-ai-plugins
claude plugin install portal@portal
claude plugin install shunt@portal

Después, en una nueva sesión de Claude Code:

/portal:setup

El plugin portal aporta el CLI de Portal que shunt usa para delegar trabajo. El README de shunt también lista jq como requisito y muestra brew install jq para macOS.

Los repositorios relevantes son:

Hay una advertencia práctica: el empaquetado se mueve rápido. El 6 de septiembre de 2026, los comandos de instalación apuntan al marketplace spotify/portal-ai-plugins, mientras que el detalle de shunt enlazado desde el artículo vive en la rama add-shunt-claude de un fork. Eso no invalida el patrón, pero sí significa que debes revisar el estado del repo antes de tratar estos comandos como documentación congelada para producción.

¿Qué tareas conviene delegar fuera de Claude Code?

Conviene delegar lecturas grandes, resúmenes acotados y generación predecible; no conviene delegar depuración sutil, edición directa ni decisiones de arquitectura.

Spotify lo dice con bastante claridad. El worker barato puede resumir patrones superficiales, pero en sus pruebas no detectó un bug sutil de thread-safety. Claude lo encontró rápido cuando recibió el contexto correcto.

Esa es la línea que conviene preservar.

La delegación funciona bien cuando la tarea es principalmente I/O o generación rutinaria:

  • Leer archivos grandes y responder una pregunta concreta.
  • Generar tests siguiendo un archivo de referencia.
  • Producir un stub de configuración desde un patrón conocido.
  • Resumir estructura de código antes de que Claude inspeccione una sección específica.

La delegación se vuelve riesgosa cuando la tarea depende de juicio:

  • Depurar una race condition.
  • Editar código con contexto exacto de líneas.
  • Decidir un tradeoff arquitectónico.
  • Revisar comportamiento sensible de seguridad.
  • Determinar si una invariante realmente se mantiene.

La regla no es “usa siempre el modelo barato”. La regla es más útil: usa el modelo barato cuando los errores son baratos, acotados y recuperables; conserva el modelo fuerte cuando los errores salen caros.

¿Qué tiene que ver esto con el precio de Claude Code?

Tiene que ver con el precio de Claude Code porque el costo real de una sesión no depende solo del plan, sino de cuántos tokens mandas al modelo fuerte y con qué frecuencia repites contexto.

OpenSEO mostró que claude code precio sí tiene demanda medible en español: 880 búsquedas mensuales en España, 390 en México, 210 en Argentina, 170 en Chile y 320 en Colombia. No uso esa frase como título porque esta no es una guía de precios. Pero sí confirma que el ángulo de costo existe en varios mercados de Iberoamerica.

La forma madura de responder esa preocupación no es prometer ahorro mágico. Es explicar dónde se va el gasto.

En una sesión larga, Claude Code puede leer archivos, recibir resultados de herramientas, conservar contexto, usar cache y ejecutar subflujos. Si cada exploración grande entra al modelo principal, el costo crece aunque la tarea final sea pequeña. El patrón de Spotify reduce ese desperdicio antes de que ocurra: bloquea la lectura grande y deriva la exploración inicial a Portal.

Eso convierte el costo en una propiedad del workflow, no en una sorpresa al final del día.

¿Cuánto puede ahorrar este patrón?

Spotify reporta ahorros medios cercanos al 90% en escenarios de lectura masiva, con casos individuales entre 82% y 94%.

Esos números vienen del benchmark publicado en el README de shunt, sobre un monorepo Java de 162.000 líneas. Los escenarios incluyen un archivo grande, un par de fuente y test, y una lectura multiarchivo entre servicios. El caso de escritura de código es más difícil de comparar porque, con shunt, el código generado puede ir directo a disco y no entrar nunca al contexto de Claude.

Hay que tratar el benchmark como self-reported. Aun así, el mecanismo tiene sentido: si Claude recibe un resumen compacto en lugar de miles de líneas, consume menos tokens. El ahorro exacto dependerá de tu repositorio, tamaño de archivos, prompts, modelo worker, frecuencia de relecturas y calidad de los resúmenes.

También hay una compensación de latencia. Spotify habla de respuestas típicas entre 10 y 30 segundos, y la invocación de acciones del Portal CLI tiene un límite de 30 segundos. Ese costo temporal puede valer la pena para archivos grandes. Para archivos pequeños, probablemente no.

Por eso existe el umbral por defecto de 350 líneas.

¿Por qué los hooks son mejores que los prompts para ahorrar tokens?

Los hooks son mejores que los prompts para ahorrar tokens porque aplican la política antes de que ocurra la llamada costosa.

Un prompt puede decir: “usa el worker barato para lecturas grandes”. Eso ayuda, pero depende de que el agente cumpla la instrucción justo en ese momento. Un hook cambia el entorno. Cuando Claude intenta leer un archivo grande completo, el hook lo bloquea y le muestra el camino esperado.

Esto conecta con una tendencia más amplia de Claude Code: los equipos están moviendo políticas operativas fuera de la prosa y dentro del runtime. En yoDEV ya vimos una pieza cercana en Claude Code ahora permite controlar cambios de modelo con hooks. La elección de modelo, el acceso a herramientas, la cache y el gasto de tokens empiezan a ser decisiones de workflow, no preferencias personales dentro de un chat.

El patrón de Spotify suma un ejemplo práctico: puedes aplicar una ruta de delegación hacia modelos baratos sin construir desde cero una plataforma interna completa de routing.

¿En qué se diferencia de otras herramientas para reducir tokens?

Se diferencia porque enruta trabajo fuera de Claude antes de crear el contexto caro.

Eso lo separa de otros enfoques cercanos. Agentmemory reduce contexto repetido guardando y recuperando memoria relevante. Turo reduce tamaño de prompt comprimiendo lenguaje antes de que llegue al modelo. Repomix empaqueta el repositorio para que un modelo lo ingiera de forma más ordenada.

El patrón de Spotify ataca otro desperdicio: lecturas completas y generación predecible que no necesitan pasar por el modelo principal.

La eficiencia de tokens no es un solo truco. Es una pila:

  • No reenvíes contexto viejo si una memoria puede recuperar la parte relevante.
  • No envíes prosa larga si una instrucción comprimida alcanza.
  • No pegues todo el repositorio si un empaquetado estructurado funciona mejor.
  • No uses un modelo fuerte para exploración masiva si un worker barato puede hacer el primer pase.

Portal encaja en el último punto.

¿Debería tu equipo copiar este patrón?

Tu equipo debería copiar este patrón si las sesiones de Claude Code gastan muchos tokens leyendo archivos grandes, generando boilerplate o explorando monorepos antes de hacer el trabajo real.

No debería copiarlo a ciegas.

Empieza por la frontera, no por el benchmark. Una primera versión razonable sería delegar solo lecturas completas de archivos grandes, permitir lecturas acotadas y dejar depuración, edición y decisiones delicadas en Claude. Después mide si los resúmenes son suficientemente buenos y si la latencia adicional vale la pena.

Para desarrolladores individuales, esto puede estirar el presupuesto de tokens sin cambiar cada prompt. Para equipos, la señal es más fuerte: plataforma puede convertir el costo de IA en una política operable.

Esa es la parte grande del post de Spotify.

El futuro del control de costo en agentes de código probablemente no será un único modelo más barato. Será routing: modelos fuertes para razonamiento, modelos worker para trabajo masivo, herramientas locales para pasos deterministas y hooks para decidir dónde está la frontera.

La versión de Spotify es temprana, opinada y ligada a Portal. Pero la idea de fondo es portable.

No le pidas al agente que sea austero.

Diseña el workflow para que las lecturas desperdiciadas nunca lleguen al modelo caro.