DEV Community: Grego

Chrome DevTools MCP para agentes: lo probamos y así maneja diálogos y consola ✅ yoDEV Tested

Grego — Tue, 03 Nov 2026 16:13:28 +0000

Chrome DevTools MCP para agentes: lo probamos y así maneja diálogos y consola ✅ yoDEV Tested

Chrome DevTools MCP 1.12 avisa a tu agente de IA cuando la página abre un alert de JavaScript y conserva la consola al cambiar de ruta. Lo probamos con un Chrome real.

https://developer.chrome.com/blog/new-in-devtools-november-2026

✅ yoDEV Tested · 3 de noviembre de 2026

chrome-devtools-mcp 1.12.0 con Chrome for Testing 153 headless en Linux, y el menú de DevTools en Chrome 156 en macOS. Los resultados que reportamos como nuestros salen de esa prueba.

El post "New in DevTools: November 2026" de Google, publicado el 20 de octubre, abre con una sección llamada DevTools for Agents. A pesar del nombre, casi nada es interfaz nueva de DevTools: son cambios en chrome-devtools-mcp, el servidor MCP de código abierto que permite a Claude Code, Gemini CLI, Copilot, Cursor y otros agentes controlar e inspeccionar un Chrome real. Lo único nuevo dentro de DevTools es una entrada de menú.

¿Qué es Chrome DevTools MCP?

Chrome DevTools MCP es un servidor Model Context Protocol, mantenido por el equipo de Chrome DevTools, que le da a un agente de IA las mismas herramientas que usa un desarrollador front-end a mano: navegar, hacer clic, llenar formularios, leer la consola y el registro de red, tomar snapshots y capturas, grabar trazas de rendimiento y ejecutar Lighthouse. Por dentro usa Puppeteer para controlar el navegador. Tu agente lo lanza en local con npx, y el servidor arranca y controla su propia instancia de Chrome.

En la versión que probamos (1.12.0, publicada en npm el 22 de octubre), el servidor expone 32 herramientas, entre ellas click, fill_form, handle_dialog, list_console_messages, get_css_styles, list_network_requests, performance_start_trace, lighthouse_audit y take_heapsnapshot.

Lo cubrimos por primera vez cuando salió como public preview en 2025: Give your AI eyes: Introducing Chrome DevTools MCP.

¿Qué cambió para los agentes en Chrome 155 y 156?

El blog de Chrome lista seis novedades bajo DevTools for Agents:

Manejo de diálogos: los diálogos de JavaScript que se abren durante una acción de entrada se manejan automáticamente.
Consola persistente: el historial de mensajes de consola se conserva en las navegaciones dentro del mismo documento.
Inspección de CSS: una herramienta nueva, get_css_styles, devuelve los estilos calculados y las reglas que aplican, con paginación.
Archivo de configuración y control de rutas: un archivo para los flags del servidor y raíces de sistema de archivos personalizadas.
Trazas por partes: las grabaciones de rendimiento grandes se procesan por bloques, con un buffer de traza de 1,2 GB por defecto.
Menú de configuración: una entrada Get Chrome DevTools for agents en el menú principal de DevTools.

Chrome 155 y 156 están en el canal estable, no solo en Canary o Beta. El servidor se publica en npm con su propio calendario, así que los cambios del servidor los obtienes actualizando el paquete, no actualizando Chrome.

¿Cómo lo probamos?

Ejecutamos chrome-devtools-mcp@1.12.0 en Linux con Node 22 contra Chrome for Testing 153 en modo headless, usando el SDK oficial de MCP para TypeScript como cliente, el mismo protocolo que habla Claude Code. La página de prueba tenía botones que abren un alert, un confirm y un prompt, y otro que llama a history.pushState. La entrada de menú la revisamos por separado en Chrome 156.0.8078.80 en macOS.

¿Qué pasa cuando la página abre un alert, confirm o prompt de JavaScript?

El servidor detecta el diálogo y le devuelve el control al agente de inmediato, pero no lo acepta ni lo cierra por su cuenta. "Manejado automáticamente" significa eso, y es la decisión correcta.

Cuando nuestro agente hizo clic en el botón del alert, la llamada a click respondió en unos 100 ms con:

The element was clicked and it opened a dialog.
# Open dialog
alert: hola desde la página.
Call handle_dialog to handle it before continuing.

Hasta que el agente responde, cualquier otra acción falla con Error: A dialog is open. El agente llama entonces a handle_dialog con action: "accept" o "dismiss", y puede pasar promptText para responder a un prompt(). En nuestra prueba, aceptar un prompt con el texto "Greg" y rechazar un confirm dejó prompt=Greg y confirm=false en la consola, tal como se esperaba.

Por qué importa: el changelog de la versión 1.7.0 corrigió un bloqueo de 180 segundos cuando se abría un diálogo durante una acción. Antes, un alert() inesperado podía congelar al agente tres minutos. Ahora lo ve en la misma respuesta y decide qué hacer, que es justo lo que quieres cuando el diálogo es un "¿Eliminar esto?".

¿El agente conserva la consola de Chrome al navegar?

Sí en las navegaciones dentro de la página, y sí bajo pedido en las cargas completas.

Navegación en el mismo documento (un cambio de #hash o history.pushState, que es como la mayoría de los routers de SPA cambian de página): list_console_messages siguió devolviendo todos los mensajes anteriores. No se perdió nada.
Navegación completa a otra URL: la lista por defecto empieza de cero con la página nueva. Con includePreservedMessages: true devuelve los mensajes de las últimas tres navegaciones, con los IDs de mensaje en secuencia. El flag --maxNavigationSaved cambia esa ventana, de 1 a 25.

Para depurar una app en React o Vue, esto significa que un error registrado en la ruta anterior sigue ahí cuando el agente lo va a buscar.

¿Qué devuelve get_css_styles?

Devuelve las reglas CSS que aplican a un elemento, en orden de cascada y con la ubicación en la hoja de estilos. Le pasas el uid del elemento que obtienes con take_snapshot. En nuestra prueba, para un botón con una regla de clase y otra dentro de un media query, devolvió primero el bloque @media (min-width: 100px), luego la regla .btn con index:1 como ubicación, y después la hoja de estilos del navegador con las propiedades sobrescritas marcadas como [overloaded]. Los resultados vienen en páginas de 10 reglas por defecto (pageSize, pageIdx), lo que evita que una hoja de estilos grande llene el contexto del agente.

¿Cómo funciona el nuevo archivo de configuración?

Ahora puedes poner las opciones del servidor en un archivo JSON en lugar de una lista larga de argumentos. El servidor busca, en este orden: un archivo indicado con --config, luego cd4a.config.json en $PLUGIN_DATA cuando corre como plugin de un agente, y luego un archivo global:

macOS y Linux: ~/.config/cd4a/config.json
Windows:       %LOCALAPPDATA%/Google/cd4a/config.json

Usa solo el primero que encuentra (no combina archivos) y los flags de la línea de comandos tienen prioridad sobre el archivo. Los nombres de las opciones van en camelCase.

Probamos el archivo global con:

{
  "headless": true,
  "isolated": true,
  "viewport": "800x600",
  "usageStatistics": false
}

Sin ninguna de esas opciones en la línea de comandos, la página reportó una ventana de 800×600 y un navegador headless, así que el archivo se aplicó. La documentación advierte que ni el archivo ni su carpeta deberían ser editables por el agente; si no, el agente podría reescribir sus propios permisos.

¿Qué errores vas a encontrar al usarlo?

Hay dos cambios de comportamiento que conviene conocer antes de conectarlo a tus scripts.

Todas las herramientas ahora piden un pageId. El enrutamiento por ID de página viene activado por defecto (--pageIdRouting). Nuestra primera ejecución falló en cada llamada con pageId: Invalid input: expected number. Agentes como Claude Code leen el esquema de las herramientas y lo resuelven solos, pero si usas el servidor directamente desde un script, llama primero a list_pages y pasa el ID.

El acceso a archivos se limita a la carpeta temporal si tu cliente no soporta MCP roots. Al arrancar, el servidor avisó que el cliente "did not negotiate the MCP roots capability" y que las herramientas que leen o escriben archivos locales quedan restringidas a la carpeta temporal del sistema. Esto afecta, por ejemplo, a guardar capturas, trazas y heap snapshots en tu proyecto. La solución es permitir carpetas concretas con --filesystemRoot (se puede repetir) o, solo con un cliente local de confianza, --allowUnrestrictedPaths. El blog de Google dice que la CLI separada chrome-devtools activa las rutas sin restricción por defecto; la documentación del servidor MCP indica false como valor por defecto, que es lo que vimos.

¿Puede el agente medir el LCP de tu página?

Sí, con una sola llamada. performance_start_trace con reload: true y autoStop: true recargó nuestra página, se detuvo sola después de unos seis segundos y devolvió el LCP (Largest Contentful Paint: 440 ms, divididos en 7 ms de TTFB y 433 ms de retraso de renderizado), el CLS y una lista de insights que el agente puede explorar en detalle. El procesamiento por bloques ocurre por dentro y no se ve desde fuera: con una página de prueba pequeña no podemos verificar el buffer de 1,2 GB ni el troceado, así que eso es la descripción de Google.

Por defecto, las URLs de las trazas se envían a la API de CrUX de Google para traer datos de usuarios reales. Desactívalo con --no-performance-crux si pruebas URLs internas.

¿Qué hace "Get Chrome DevTools for agents"?

En Chrome 156, la entrada está en el menú de tres puntos de DevTools. Al hacer clic abre el repositorio del proyecto en GitHub. Es un atajo a las instrucciones de instalación, no un instalador dentro de DevTools.

¿Cómo instalar Chrome DevTools MCP en Claude Code, Gemini CLI y VS Code?

Necesitas Node.js en versión LTS actual, npm y Chrome estable o más reciente.

Claude Code:

/plugin marketplace add ChromeDevTools/chrome-devtools-mcp
/plugin install chrome-devtools-mcp@chrome-devtools-plugins

Gemini CLI:

gemini extensions install --auto-update https://github.com/ChromeDevTools/chrome-devtools-mcp

Copilot en VS Code: ejecuta "Chat: Install Plugin From Source" e ingresa ChromeDevTools/chrome-devtools-mcp.

Cualquier otro cliente MCP (Cursor, Codex y otros), con el bloque de configuración estándar:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

Flags útiles para añadir: --isolated para un perfil temporal que se borra al cerrar el navegador, --headless para no abrir ventana, --slim para un conjunto reducido de tres herramientas (navegación, ejecución de scripts y capturas) y --no-usage-statistics para no enviar datos de uso.

Una advertencia del propio proyecto: el servidor expone el contenido de su navegador al cliente MCP. No lo apuntes a sesiones con datos que no compartirías con tu agente, y prefiere --isolated antes que tu perfil de todos los días.

¿Chrome DevTools MCP o Playwright MCP?

Si tu trabajo es depurar y medir una app en Chrome, Chrome DevTools MCP; si necesitas Firefox o WebKit, Playwright MCP. Según su README, Playwright MCP (de Microsoft) soporta Chromium, Firefox y WebKit, trabaja sobre el árbol de accesibilidad y también tiene herramientas para diálogos (browser_handle_dialog) y consola (browser_console_messages); las trazas son opcionales con --caps=devtools y no menciona Lighthouse ni análisis de rendimiento. Chrome DevTools MCP solo soporta oficialmente Google Chrome y Chrome for Testing, pero trae lo que viene de DevTools: insights de rendimiento con LCP, lighthouse_audit, heap snapshots y ahora get_css_styles. Playwright MCP no lo probamos para esta nota.

¿Vale la pena actualizarlo?

Sí. Los cambios en diálogos y consola resuelven dos situaciones reales en las que un agente se quedaba trabado o ciego al probar una app web, y ambos se comportaron como describe Google en nuestra prueba. El archivo de configuración hace que el setup sea reproducible en todo el equipo. Solo ten en cuenta el pageId obligatorio y la restricción a la carpeta temporal antes de integrarlo en tus scripts.

Al momento de publicar esta nota, el número de herramientas (32), los valores por defecto y el comportamiento del menú corresponden a la versión 1.12.0 y a Chrome 156; el proyecto publica versiones con frecuencia, así que revisa el changelog antes de depender de un valor por defecto concreto.

¿Y tú? ¿Qué es lo primero que le pedirías revisar a tu agente en el navegador: un error de consola, una petición de red o el rendimiento?

Relacionado: BrowserSkill: cómo darle a Claude Code tu navegador real con la sesión ya iniciada

Permisos asistidos en GitHub Copilot CLI: el término medio entre aprobar todo y --yolo

Grego — Fri, 30 Oct 2026 16:26:39 +0000

Los permisos asistidos (assisted permissions) de GitHub Copilot CLI, la app de Copilot y VS Code hacen que un modelo revise cada solicitud del agente y apruebe solo las que considera seguras; el resto te las sigue preguntando a ti. Están disponibles de forma general desde el 26 de octubre.

https://github.blog/changelog/2026-10-26-github-copilot-assisted-permissions-generally-available/

Si usas el agente de Copilot a diario, conoces las dos opciones que había hasta ahora. La aprobación manual es segura, pero te interrumpe cada pocos segundos. El modo allow-all (--allow-all, --yolo) elimina las interrupciones y, con ellas, tu control sobre cada acción. Los permisos asistidos son la propuesta de GitHub para el término medio.

¿Qué son los permisos asistidos en GitHub Copilot?

Son un modo de permisos en el que un modelo, y no tú, toma la primera decisión sobre las solicitudes elegibles. Según la documentación de GitHub, hay tres tipos de solicitudes elegibles:

ejecutar un comando
acceder a una ruta del sistema de archivos
abrir una URL

Para cada una, el modelo comprueba si la acción es segura y si está dentro de la autoridad que le diste a Copilot para la tarea. El resultado es uno de dos:

Está seguro de que es segura: Copilot la aprueba y continúa sin preguntarte.
No está seguro: Copilot te pregunta, exactamente como lo haría con aprobación manual.

Algunas cosas quedan fuera de la revisión. Las solicitudes que ya tenías permitidas se ejecutan sin preguntar y sin pasar por el modelo. Las reglas de denegación y las restricciones de la empresa siguen aplicándose. Las demás llamadas a herramientas que las reglas de la empresa obligan a aprobar, y las solicitudes para saltarse el sandbox local, no las revisa el modelo: siguen el flujo normal de permisos de la sesión. Si la revisión no está disponible o no puede evaluar una solicitud, esa solicitud también vuelve al flujo normal.

El modelo que hace la revisión no es necesariamente el mismo con el que estás conversando. Copilot elige el modelo revisor; si no está disponible, la revisión puede usar el modelo activo de tu sesión. Si usas tu propio proveedor de modelos, la revisión usa siempre el modelo activo de la sesión.

¿Permisos asistidos, aprobación manual o --yolo?

Modo	Revisión por modelo	Cuándo te pregunta	Supervisión
Aprobación manual	No	En cada acción que no esté ya permitida (aprobación única o para toda la sesión)	Máxima
Permisos asistidos	Sí, en solicitudes elegibles	Solo cuando el modelo no está seguro	Menos interrupciones, sin permiso global
Allow-all (`--allow-all`, `--yolo`, `/permissions allow-all`, `/yolo`)	No	Nunca	Ninguna por acción

La diferencia práctica: allow-all concede la confianza por adelantado para toda la sesión. Los permisos asistidos la conceden solicitud por solicitud, según un juicio sobre esa acción concreta.

¿Cómo se activan en Copilot CLI, la app y VS Code?

En Copilot CLI

Dentro de una sesión interactiva:

/permissions assisted los activa solo para la sesión actual
/permissions manual vuelve a la aprobación manual
/permissions show muestra el modo actual
/permissions sin argumentos abre una lista para elegir

Para que sea el modo por defecto en todas las sesiones interactivas nuevas, añade esto a ~/.copilot/settings.json:

{
  "defaultPermissionMode": "assisted"
}

Cámbialo a "manual" para volver atrás.

En ejecuciones no interactivas (scripts, CI), usa el flag o la variable de entorno:

copilot -p "Fix the failing tests" --assisted-approval

COPILOT_ASSISTED_APPROVAL=true

--assisted-approval es solo para ejecuciones no interactivas: si lo usas para iniciar una sesión interactiva, el comando termina con un error.

En la app de GitHub Copilot

Abre el menú de modo, elige Tool permissions y luego Assisted. Esto también lo guarda como predeterminado para las nuevas sesiones locales. Para cambiar solo la sesión actual, escribe /permissions assisted en el cuadro de prompt.

En VS Code

Selecciona Assisted permissions en el selector de permisos del chat. Según la documentación de VS Code, hay tres condiciones:

La opción no está disponible en sesiones con el harness Local.
Tienes que elegir aislamiento Folder: las sesiones en Worktree usan siempre Allow all.
La primera vez que eliges este nivel, un diálogo de advertencia te pide confirmación.

El nivel con el que arrancan las sesiones nuevas se define con la configuración chat.permissions.default.

¿Qué pasa en modo autopilot y en CI?

En modo autopilot y en ejecuciones no interactivas no hay nadie a quien preguntar, así que las solicitudes que necesitarían tu aprobación se deniegan. La explicación del modelo vuelve a Copilot, para que el agente pruebe otro camino en lugar de quedarse bloqueado.

Para la automatización, esto es lo más importante: con permisos asistidos, una ejecución desatendida se cierra en negativo ante cualquier cosa sobre la que el modelo no esté seguro.

¿Cómo se bloquea --yolo para todo el equipo?

Aquí la función se convierte en una herramienta de gobernanza. Los administradores de una empresa pueden usar la configuración gestionada (enterprise-managed settings) para controlar qué modos pueden usar los desarrolladores:

permissions.disableBypassPermissionsMode: "disable" bloquea la aprobación incondicional (allow-all) sin desactivar los permisos asistidos
permissions.disableAssistedPermissionsMode: true desactiva los permisos asistidos
permissions.defaultMode define un modo predeterminado gestionado para las sesiones nuevas, que tiene prioridad sobre el defaultPermissionMode de cada desarrollador

Los desarrolladores pueden cambiar a cualquier otro modo que la política permita. Si el modo predeterminado configurado no está disponible o está prohibido, la sesión arranca con aprobación manual.

La primera opción es la interesante. Hasta ahora, un equipo que quería menos interrupciones tenía que tolerar que sus desarrolladores usaran --yolo. Ahora un administrador puede sacar --yolo de la mesa y dejar los permisos asistidos como la opción rápida.

Referencia: https://docs.github.com/enterprise-cloud@latest/copilot/reference/enterprise-administrators/enterprise-managed-settings#permissions

¿Es seguro usarlo sin sandbox?

No por sí solo, y GitHub lo dice sin rodeos. Su documentación advierte que el modelo puede equivocarse y aprobar acciones peligrosas o no deseadas, y que la función no sustituye al sandboxing ni a las restricciones de acceso. Menos interrupciones no te quitan la responsabilidad sobre lo que hace Copilot.

Antes de meter esto en un pipeline, hay dos detalles de la CLI que conviene revisar:

Los flags no se anulan entre sí. --assisted-approval anula --allow-all-tools, pero --allow-all-paths y --allow-all-urls siguen aplicándose. Si combinas los permisos asistidos con --allow-all o --yolo, el acceso a rutas y URLs puede quedar sin restricciones.
Puede fallar en silencio. Si los permisos asistidos no se pueden activar (por ejemplo, porque la configuración de la empresa los bloquea), la CLI escribe una advertencia en la salida de error estándar y cualquier --allow-all-tools que hayas pasado sigue aplicándose. En ejecuciones automatizadas, revisa stderr en busca de esa advertencia.

Uno más para entornos empresariales: en la CLI, las reglas ask de la empresa para comandos de shell, lecturas de archivos, escrituras de archivos y URLs pueden darse por satisfechas con la aprobación del modelo. Una regla ask ya no garantiza que una persona vea la solicitud.

La configuración sensata es usar permisos asistidos dentro de un entorno aislado, no en lugar de uno. Explicamos cómo activar el sandbox local de Copilot aquí: Sandbox local de GitHub Copilot: cómo activarlo en la CLI, la app y VS Code y qué no bloquea.

¿En qué planes de Copilot está disponible?

Al momento de publicar esta nota, ni el changelog ni la documentación de GitHub indicaban en qué planes de Copilot están incluidos los permisos asistidos.

¿Y tú? ¿Qué acción nunca dejarías que un modelo aprobara sin preguntarte?

Relacionado: GitHub Copilot Apuesta por la Autonomía — Y Construye el Guardrail para Contenerla

Claude Code Spends ~16% of Your Tokens on a Status Line: How to Measure agent_summary and Turn It Off ✅ yoDEV Tested

Grego — Fri, 30 Oct 2026 15:20:35 +0000

Claude Code envía en segundo plano una petición llamada agent_summary que, según la telemetría de un desarrollador independiente, se llevó el 16,4 por ciento de todo el gasto en tokens y casi 1 de cada 5 peticiones a la API, solo para actualizar una línea de estado de tres a cinco palabras por cada agente en segundo plano. Cada ~30 segundos, por cada agente activo, Claude Code reenvía la transcripción completa de ese agente a su propio modelo (normalmente Opus) y le pide que describa su última acción. Puedes medirlo en tu propia máquina con OpenTelemetry, y un script de precarga para Bun con licencia MIT, no-agent-summary.js, lo desactiva.

Fuente: README y script de no-agent-summary.js en GitHub Gist

yoDEV Tested · 29 de octubre de 2026
Probamos no-agent-summary.js con Claude Code 2.1.312 en macOS 27.0.1 (Apple Silicon), una plataforma que su autor no ha probado, revisamos los binarios Linux x64 de 2.1.312 y 2.1.308 en un sandbox y reprodujimos dos fallos de instalación en Bun 1.4.4. Los resultados que reportamos como nuestros salen de esa prueba.

¿Qué es Claude Code y qué son los agentes en segundo plano?

Claude Code es el agente de programación de Anthropic que trabaja desde la terminal: lee tu repositorio, ejecuta comandos y edita archivos. Puede delegar trabajo en subagentes y dejar algunos corriendo en segundo plano (background agents) mientras tú sigues con otra cosa. El panel de agentes muestra, junto a cada uno, una línea corta que resume qué está haciendo. Esa línea es la que cuesta.

¿Qué es agent_summary en Claude Code?

agent_summary es el query_source que Claude Code asigna a la petición que escribe ese texto de estado junto a cada agente en segundo plano. La respuesta nunca llega al modelo ni a tu conversación: solo actualiza esa etiqueta.

Según el autor del script, Flamerix AI:

Está activado por defecto para los agentes en segundo plano en modo interactivo desde la 2.1.232 (agosto de 2026).
El intervalo viene de un flag del servidor, limitado a entre 30 y 240 segundos, y el valor por defecto ya es el mínimo de 30.
No hay ningún ajuste para apagarlo. La opción del SDK agentProgressSummaries puede encenderlo pero no apagarlo, y la variable no documentada CLAUDE_CODE_AGENT_PROGRESS_SUMMARIES también solo sirve para activarlo.
En la 2.1.310 llegó un modo “short” más barato, unos 2.000 tokens de notas en lugar de la transcripción entera, pero viene apagado y solo los flags del servidor pueden cambiarlo.

Todo esto es la lectura que hace el autor del código empaquetado, no documentación de Anthropic.

¿Cuánto suma agent_summary al precio de Claude Code?

En una semana de uso del autor, agent_summary costó más que la conversación principal. Las cifras son autorreportadas, salen de su propia exportación de OpenTelemetry y no publicó los datos en bruto:

`query_source = agent_summary`	Semana antes del hook	2 días después
Parte del gasto de Claude Code	16,4% (conversación principal: 15,7%)	0%
Parte de las peticiones a la API	19,7%	0%
De ese gasto, en Opus	96%	—
Tokens de entrada por token de salida	≈ 9.000 : 1	—

“Gasto” aquí es la estimación que hace el propio Claude Code por petición (cost_usd), no una factura. Si usas un plan de suscripción, lo que pierdes es margen frente a los límites de uso.

El autor no es el único. El issue #86879 es una petición abierta para tener una forma oficial de desactivar el temporizador, y reúne mediciones de entre el 18 y el 26 por ciento en sesiones distintas, incluida una donde agent_summary fue el 22,7 por ciento de las peticiones. El coste crece con cuántos agentes en segundo plano tienes y durante cuánto tiempo, no con el trabajo útil, porque cada ciclo reenvía el contexto actual del agente. Un comentarista en la 2.1.276 calculó que un agente con ~380.000 tokens de contexto paga unos 45 millones de tokens leídos de caché por hora solo por su línea de estado.

La caché de prompts lo suaviza, pero no lo elimina: según el autor, casi todas estas llamadas aciertan en la caché, y la pequeña fracción que falla carga con más de un tercio del coste.

Al momento de publicar esta nota, el 29 de octubre de 2026, ninguno de los dos issues tenía respuesta de Anthropic, y Anthropic no había confirmado públicamente este comportamiento.

¿Por qué Claude Code consume tokens en segundo plano sin que lo veas?

Porque estas peticiones no se escriben en las transcripciones de sesión que se guardan en disco. El issue #104358 documenta que las peticiones de fondo (agent_summary, compact, las llamadas del clasificador de auto_mode y otras) se cobran pero no dejan ninguna fila en esos archivos, así que cualquier herramienta que sume transcripciones se queda corta. Quien lo reportó encontró totales entre 1,35 y 2,13 veces por debajo del estado de costes del propio Claude Code, en 14 sesiones con muchos subagentes.

La exportación de OpenTelemetry es el único lugar donde aparecen.

¿Cómo ver el consumo de tokens en Claude Code por tipo de petición?

Activa la exportación de logs de OpenTelemetry de Claude Code y agrupa los eventos claude_code.api_request por query_source. Según la documentación oficial de Monitoring, el valor detallado de query_source (como repl_main_thread, compact o el nombre de un subagente) vive en el evento api_request. Las métricas claude_code.cost.usage y claude_code.token.usage solo llevan una categoría gruesa (main, subagent o auxiliary), así que con métricas solas no puedes aislar agent_summary.

La configuración mínima, según la documentación:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
claude

Apunta el endpoint al colector OTLP que ya uses y suma cost_usd (o los atributos de tokens) por query_source. Si no llega nada, la documentación recomienda arrancar Claude Code con claude --debug-file <ruta> y buscar errores [3P telemetry] en ese log.

Una comprobación rápida sin colector: el método del propio autor cuenta las líneas [AgentSummary] Forking de un log de --debug-file mientras corre un subagente en segundo plano. Si esa línea aparece cada ~30 segundos por agente, estás pagando por ella.

Si también usas Codex, tenemos la guía equivalente: Cómo ver el consumo de tokens en Codex CLI.

¿Cómo desactivar agent_summary en Claude Code?

Con no-agent-summary.js, una precarga para Bun de unas 80 líneas. El binario nativo de Claude Code es un programa de Bun compilado, y Bun lee opciones extra de la variable de entorno BUN_OPTIONS, así que el script se carga antes que Claude Code sin modificar el binario.

El script envuelve setTimeout y setInterval. Cuando el código del callback de un temporizador contiene una de sus dos anclas, la línea de log [AgentSummary] Timer fired o el id agent_summary, devuelve un temporizador inerte en lugar de armarlo. Todos los demás temporizadores pasan sin cambios.

⚠️ Dos reglas que el README no dice. Escribe --preload=/ruta, no --preload /ruta: con un espacio, poner BUN_OPTIONS de forma global rompe todos los subcomandos de bun. Y guarda el hook en una ruta sin espacios, porque BUN_OPTIONS no puede llevarlos, la entrecomilles como la entrecomilles. Reprodujimos los dos fallos (ver “¿Qué se rompe al instalarlo?”, más abajo). Todos los comandos de aquí usan la forma con = y la ubicación que propone el README, ~/.local/share/.

Para una sola sesión (adaptado del resumen del README):

curl -fsSL https://gist.githubusercontent.com/flamerix-ai/c3905705cc4205e5de3011fa2e74efce/raw/no-agent-summary.js -o ~/.local/share/no-agent-summary.js
claude daemon stop --any
BUN_OPTIONS="${BUN_OPTIONS:+$BUN_OPTIONS }--preload=$HOME/.local/share/no-agent-summary.js" claude

De forma permanente, añade esto a ~/.profile, ~/.bashrc o ~/.zshrc, con la ruta absoluta:

export BUN_OPTIONS="${BUN_OPTIONS:+$BUN_OPTIONS }--preload=/ruta/absoluta/no-agent-summary.js"

Después reinicia el daemon para que los procesos en segundo plano lo tomen:

claude daemon stop --any

Ese reinicio importa. El daemon, el pty host y las sesiones bg-spare precalentadas heredan el entorno de lo que arrancó el daemon, así que un daemon iniciado antes de definir BUN_OPTIONS sigue creando sesiones sin el hook. Las ejecuciones sin interfaz (claude -p, cron, CI, integraciones con editores) también necesitan la variable.

Qué cambia: la línea de estado de cada agente en el panel deja de actualizarse. Los subagentes, los agentes en segundo plano, los skills bifurcados y las sesiones en segundo plano siguen funcionando con normalidad.

¿Se puede sin parche?

En parte. El README indica que CLAUDE_CODE_FORK_SUBAGENT=0 y CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 también detienen los resúmenes, pero solo porque apagan por completo los subagentes bifurcados o los agentes en segundo plano. La variable que se suele sugerir, DISABLE_NON_ESSENTIAL_MODEL_CALLS, ni siquiera existe en el binario: la buscamos en las dos versiones que probamos y no aparece ni una vez.

¿Qué se rompe al instalarlo?

Hay tres maneras distintas de que salga mal. Las dos primeras las reprodujimos nosotros.

1. Un BUN_OPTIONS global con espacio rompe Bun

Un comentario en el gist reportó que BUN_OPTIONS="--preload /ruta" hace fallar bun install, add, test, build y x con Script not found "install" (y similares) en Bun 1.4.3. La causa es el analizador de argumentos de Bun: cualquier flag con valor colocado antes del subcomando lo provoca; bun --define x:1 install falla igual.

Lo reprodujimos en Bun 1.4.4:

`BUN_OPTIONS`	`bun install`	`bun test`	`bun build`	`bun x`
`--preload /ruta`	`Script not found "install"`
`--preload=/ruta`
sin definir

Con --preload=/ruta, el hook sigue cargando en Claude Code 2.1.312 y 2.1.308. El arreglo no cuesta nada del lado de Claude Code. En macOS vimos lo mismo con el Bun independiente 1.3.13.

El mismo comentarista también restringió la comprobación de instalación del script para que solo actúe dentro del binario de Claude Code, y así otros binarios de Bun compilados en la máquina no vean sus temporizadores envueltos. Tal como está publicado, el script solo verifica que corre dentro de algún binario de Bun compilado. Esa modificación no la probamos.

2. Un espacio en la ruta del hook impide que Claude Code arranque

Bun separa BUN_OPTIONS por espacios, así que una ruta como ~/mis pruebas/no-agent-summary.js se parte en dos. Nos pasó en nuestra primera prueba en macOS, desde una carpeta cuyo nombre tenía un espacio. Bun leyó la segunda mitad como un flag suelto (error: Invalid Argument '-s'), y todos los comandos que definían BUN_OPTIONS, claude incluido, imprimieron la ayuda de Bun y terminaron.

Entrecomillar no sirve. En el sandbox probamos la ruta tal cual, entre comillas dobles, entre comillas simples y con los espacios escapados con barra invertida. Las cuatro fallaron con preload not found, con la ruta cortada en el primer espacio. El archivo del hook tiene que estar en una ruta sin espacios.

Al menos este fallo es visible: Claude Code se niega a arrancar, en lugar de correr sin el hook.

3. Cualquier actualización de Claude Code puede deshacerlo en silencio

El hook reconoce el temporizador del resumen por texto dentro de su callback. Si una actualización renombra la línea de log o el id, saca esos textos fuera del callback, pasa el callback por .bind() o mueve el temporizador a una API que el script no envuelve, el hook no detecta nada y los resúmenes vuelven sin avisar. El autor lo llama “fail-open”.

Por eso conviene volver a verificarlo después de cada actualización:

BUN_OPTIONS="--preload=$HOME/.local/share/no-agent-summary.js" CC_AGENT_SUMMARY_LOG=/tmp/nas.log claude --version && cat /tmp/nas.log

Deberías ver preload active mode=off …. Después, con las mismas variables, deja correr un subagente en segundo plano un minuto o dos: el log debería mostrar summary timer #1 suppressed. Si exportas OpenTelemetry, que query_source = agent_summary se mantenga en cero es la única comprobación que detecta todos los modos de fallo.

Para una prueba A/B, CC_AGENT_SUMMARY_MODE=pass carga el hook pero deja armados todos los temporizadores. Los resúmenes vuelven, lo que demuestra que es el modo off el que los elimina.

Ten en cuenta también:

Plataforma: el autor solo lo probó en Linux. Nuestra prueba, más abajo, muestra que funciona en macOS (Apple Silicon) con la 2.1.312. En Windows, según el autor, lo más probable es que el hook nunca se instale.
Términos de servicio: el README advierte que cambiar el comportamiento de un cliente en ejecución puede entrar en conflicto con los términos del servicio con el que lo usas, y deja esa comprobación en tus manos.

¿Qué probamos en yoDEV?

Hicimos dos pruebas el 29 de octubre de 2026.

En macOS: ¿el hook realmente detiene agent_summary?

Entorno: Claude Code 2.1.312, el binario nativo arm64 con Bun 1.4.4 integrado, en macOS 27.0.1 sobre Apple Silicon. El hook se descargó desde la URL del propio README; su sha256 es dc6699da…59f7.

Seguimos el método del autor: tres sesiones sin interfaz (claude -p --model haiku, con los resúmenes forzados mediante CLAUDE_CODE_AGENT_PROGRESS_SUMMARIES=1). En cada una, un subagente ejecutó ocho pasos de 20 segundos, y contamos las líneas [AgentSummary] Forking en el log de --debug-file.

Ejecución	Disparos del temporizador	Bifurcaciones de resumen	Duración
Sin hook	5	5	181 s
Hook en modo `pass` (control)	5	5	220 s
Hook en modo `off`	0	0	212 s

El resultado coincide con el del autor en Linux para la 2.1.312: la bifurcación ocurre, cargar el hook por sí solo no cambia nada, y el modo off la elimina. El subagente completó los ocho pasos en todas las ejecuciones.

El log del hook en modo off muestra el mecanismo: un temporizador suprimido, unos 26 segundos después de empezar. Un temporizador suprimido nunca se dispara, así que nunca se vuelve a armar, y el log de depuración no muestra ninguna línea Timer fired ni Forking.

El log sin hook también muestra qué se paga en cada una de esas llamadas. Cada bifurcación reenvió el contexto completo del subagente (23 mensajes en el primer ciclo) para producir un resumen como “Running sleep 20, call 1 of 8”.

En un sandbox Linux x64: ¿encaja con las versiones actuales?

Con el paquete de npm @anthropic-ai/claude-code-linux-x64:

Comprobación	2.1.312 (latest)	2.1.308 (stable)
El prefijo sha256 coincide con la tabla del README	`4f4178ce41d8`	`356733f185fa`
Anclas del hook presentes en el binario
La precarga carga y envuelve los temporizadores
Existe `claude daemon stop --any`
`DISABLE_NON_ESSENTIAL_MODEL_CALLS` en el binario	0 apariciones	0 apariciones

Lo que no medimos: la parte del gasto. Nuestras ejecuciones demuestran que la llamada desaparece, pero no verifican la cifra del 16,4 por ciento del autor, que depende de cuántos agentes en segundo plano uses y durante cuánto tiempo. Por eso la sección de medición va primero.

¿Vale la pena instalarlo?

Si dejas agentes en segundo plano corriendo durante mucho tiempo, sobre todo sin supervisión o en CI, donde nadie mira la línea de estado, mide primero. Si agent_summary aparece como una parte grande de tus eventos api_request, el hook es un script pequeño y legible, con un interruptor de control (modo pass) y una forma clara de verificarlo. Instálalo con --preload= en una ruta sin espacios, reinicia el daemon y vuelve a comprobarlo después de cada actualización de Claude Code.

Si trabajas sobre todo en una sola sesión en primer plano, sin agentes en segundo plano, puede que no estés pagando nada de esto, y eso es justo lo que la medición te va a decir.

Si quieres entender mejor qué estás pagando en cada petición, empieza por qué son los tokens en la IA y por qué te cobran por ellos.

¿Y tú? ¿Qué parte de tu consumo de tokens en Claude Code te sorprendió más cuando lo mediste?

Tsrs, Probado: el Port de TypeScript 7 a Rust Fue Hasta 6,5x Más Rápido que tsc (y te Pasa a 7.1) ✅ yoDEV Tested

Grego — Sun, 25 Oct 2026 15:48:19 +0000

tsrs es un port a Rust del compilador de TypeScript 7 que ya puedes instalar desde npm, y en nuestra prueba fue entre 2,9x y 6,5x más rápido que tsc 7.0.2, con entre 2x y 4,2x menos memoria. Cloudflare, VoidZero y Max Schwenk, de Owner.com, lo anunciaron el 20 de octubre de 2026. El proyecto se incuba dentro del toolchain Oxc y se desarrolla en colaboración con el equipo de TypeScript.

https://blog.cloudflare.com/typescript-rust-port/

✅ yoDEV Tested · 20 de octubre de 2026 Ejecutamos tsrs 0.18.0 frente a tsc 7.0.2, tsc-rs 0.7.0 y bun check 1.4.3 sobre zod, playwright y hono, en una máquina Linux de 2 vCPU. Los resultados que reportamos como nuestros salen de esa prueba.

¿Qué es tsrs, el compilador de TypeScript en Rust?

tsrs es un reemplazo directo (drop-in replacement) del compilador de TypeScript 7 (tsc) y de su servidor de lenguaje, escrito en Rust. Lee tu tsconfig.json actual, emite JavaScript y declaraciones igual que tsc, y admite --watch, -b y un modo LSP para editores. Su objetivo declarado es 100 por ciento de conformidad con TypeScript, con menos memoria y un type checking más rápido.

No es un fork. El anuncio de Cloudflare lo deja claro: el equipo de TypeScript sigue controlando el diseño del lenguaje, y tsrs debe seguir las decisiones de upstream, no tomar las suyas. Hoy sigue la rama principal de microsoft/TypeScript, y cada versión del paquete indica el commit que porta: 0.18.0-ts7.1.0-dev.20260929 es tsrs 0.18.0 siguiendo TypeScript 7.1.0-dev.20260929.

Dos datos que conviene saber desde el principio:

Lo escribieron agentes de IA. Max Schwenk, Head of AI Developer Experience en Owner.com, lo empezó el 30 de septiembre preguntándose si Claude Opus 5.5 podía portar el compilador a partir del código en Go de TypeScript. Según su propio relato, no escribió código él mismo: los agentes trabajaron con la suite de conformidad de TypeScript como especificación. El 19 de octubre el proyecto pasó a oxc-project/tsrs, bajo Cloudflare y VoidZero.
Por qué lo construyó Owner.com. Su código principal tiene unos 37.000 archivos TypeScript. Con TypeScript 7.0, un chequeo con un solo hilo tardaba 80 segundos y usaba 19 GiB de memoria. Con tsrs, Owner reporta unos 7 segundos en CI.

Licencia: Apache-2.0, como derivado de TypeScript. El README aclara que no está afiliado ni respaldado por Microsoft.

¿Cómo instalar tsrs?

Agrégalo como dependencia de desarrollo y ejecútalo donde ejecutarías tsc:

pnpm add -D tsrs
pnpm exec tsrs --noEmit

Con npm, el anuncio de Cloudflare usa:

npm install tsrs
npx tsrs

Para probarlo sin agregarlo al proyecto: pnpm dlx tsrs -p .

Comandos útiles de la documentación de uso:

pnpm exec tsrs -p path/to/project           # compilar
pnpm exec tsrs -p path/to/project --noEmit  # solo type check
pnpm exec tsrs -p . --extendedDiagnostics   # contadores y tiempos
pnpm exec tsrs --version
tsrs --watch -p .                           # recompila al guardar
tsrs --lsp -stdio                           # servidor de lenguaje para el editor

El launcher de npm instala un binario nativo para tu plataforma como dependencia opcional @tsrs/<os>-<arch>. También hay un playground en el navegador (tsrs-playground.void.app) y una build en WebAssembly, @tsrs/wasm, para Node y navegadores.

Lo que todavía no hace: --init y --showConfig no están soportados, así que mantén tsc a mano para generar la configuración.

¿tsrs es más rápido que tsc? Nuestro benchmark

Sí: en nuestra prueba fue entre 2,9x y 6,5x más rápido que tsc 7.0.2 (el compilador en Go, también conocido como tsgo). La cifra de "hasta 8x más rápido" con alrededor de 70 por ciento menos memoria es el benchmark propio de Cloudflare: tsrs contra TypeScript 7.0 con el mismo número de workers de chequeo. El benchmark publicado por el proyecto usó 17 proyectos en una máquina de CI de 16 vCPU y 63 GB, y el código está en el repo, en bench/.

Queríamos números en una máquina más chica, así que repetimos el montaje de nuestra prueba de bun check: los mismos tres repos, 2 vCPU, 7 GB de RAM, una ejecución de calentamiento más cinco medidas (diez en hono), mediana del tiempo total y pico de memoria.

Proyecto	tsc 7.0.2	tsrs 0.18.0	tsc-rs 0.7.0	bun check 1.4.3
zod (593 errores)	5,82 s · 1.118 MB	0,90 s · 266 MB	1,46 s · 632 MB	1,42 s · 192 MB
playwright (5.664 errores)	3,12 s · 581 MB	0,73 s · 195 MB	1,19 s · 417 MB	1,05 s · 189 MB
hono, config de build (limpio, 364 archivos)	0,32 s · 98 MB	0,11 s · 49 MB	0,10 s · 103 MB	—

Frente a tsc 7.0.2, tsrs fue:

zod: 6,5x más rápido, 4,2x menos memoria
playwright: 4,3x más rápido, 3,0x menos memoria
hono: 2,9x más rápido, 2,0x menos memoria

Dos cosas nos llamaron la atención. Primero, la ganancia no es solo paralelismo: con un único hilo de chequeo en ambos (--checkers 1), tsrs siguió siendo 4,8x más rápido en zod y 3,3x en playwright. Segundo, se sostiene en proyectos chicos. En nuestra prueba anterior, bun check fue más lento que tsc en el build limpio de hono; tsrs fue casi tres veces más rápido con la misma configuración.

¿tsrs o bun check?

tsrs fue más rápido que bun check en los dos repos grandes. En memoria quedaron parejos en playwright, pero en zod tsrs usó más (266 MB frente a 192 MB). Si la memoria te importa más que la velocidad, --checkers 1 bajó tsrs a 195 MB en zod y se mantuvo por debajo de 1,2 segundos.

¿Qué flags controlan la velocidad y la memoria?

tsrs agrega algunas opciones de rendimiento a los flags estándar de tsc:

--checkers N define cuántos hilos de chequeo usar. Por defecto, uno por núcleo hasta 16.
--singleThreaded usa un solo hilo, para el menor consumo de memoria.
--maxMemory <size> (por ejemplo 12G, solo con --noEmit) mantiene el proceso cerca de ese límite, cambiando CPU por memoria.
--checkerCostCache <file> recuerda cuánto tardó cada archivo para repartir mejor los hilos en la siguiente ejecución.

¿tsrs da los mismos errores que tsc? El cambio a TypeScript 7.1

Sí, siempre que lo compares con la versión de TypeScript que realmente porta, y ahí está el detalle: tsrs sigue TypeScript 7.1-dev, no 7.0.

En zod, tsrs y tsc 7.0.2 reportaron los mismos 593 errores, línea por línea. En playwright, ambos reportaron 5.664 errores, pero 20 aparecieron en otra línea y columna. En la configuración de build de hono, tsc 7.0.2 terminó limpio y tsrs reportó dos errores nuevos TS7031 (any implícito).

Después ejecutamos typescript@7.1.0-dev.20260930.4, la build del commit que porta tsrs. Su salida coincidió exactamente con tsrs en ambos repos. Las diferencias son comportamiento de TypeScript 7.1, no bugs de tsrs.

En la práctica: cambiar tsc 7.0 por tsrs en tu CI significa pasar tu type check a la semántica de 7.1-dev. Un repo que hoy está limpio puede empezar a fallar. Pruébalo primero en local y trátalo como una actualización, no como un cambio transparente.

Un detalle más para CI: con errores, tsc 7.0.2 salió con código 1 y tsrs con código 2. TypeScript 7.1-dev también devuelve 2. Los dos son distintos de cero, así que el paso de CI falla igual, pero un script que compare exactamente con 1 no.

El propio proyecto dice que quiere reducir las diferencias que quedan, como el orden en que se imprimen los diagnósticos, antes de una versión estable. Para la comparación más cercana con el compilador en Go, el README sugiere --checkerAssignment go --noLazyMembers.

tsrs vs tsc-rs: ¿qué port de TypeScript a Rust usar?

Son dos paquetes de npm distintos con nombres casi idénticos, y es fácil confundirlos.

	tsrs	tsc-rs
Paquete npm	`tsrs`	`tsc-rs`
Repo	`oxc-project/tsrs`	`pingdotgg/ts-rust`
Detrás	Oxc, Cloudflare, VoidZero; nació en Owner.com	pingdotgg (Theo Browne)
Licencia	Apache-2.0	MIT AND Apache-2.0 (npm)
Porta	TypeScript 7.1-dev	TypeScript 7.1-dev
Cómo se escribió	Agentes de IA (Claude Opus 5.5)	Agentes de IA: primero modelos de OpenAI, luego Claude Opus 5.5

Los dos son ports escritos por LLM a partir del mismo compilador en Go. El README de tsc-rs cuenta que el primer intento con modelos de OpenAI costó más de 400.000 dólares en tokens a precio de API y se estancó cerca del 84 por ciento de compatibilidad, y que el reinicio con Claude Opus 5.5 tomó unas dos semanas y unos 24.000 dólares.

En nuestra prueba, los dos dieron diagnósticos idénticos en los tres repos. tsrs fue alrededor de 1,6x más rápido en los repos grandes y usó cerca de la mitad de memoria; en hono empataron en tiempo y tsrs usó la mitad de memoria.

La elección puede no durar. El anuncio de Cloudflare dice que están trabajando con Theo Browne para fusionar tsc-rs y tsrs en un solo paquete. Al 20 de octubre de 2026, esa fusión está anunciada pero no publicada, y el README de ts-rust todavía no la menciona.

¿tsrs está listo para producción?

Es una versión experimental con un camino claro hacia una estable. Cloudflare la llama experimental; el README, en cambio, nombra limitaciones concretas en vez de una advertencia general, y dice que en sus pruebas sobre proyectos existentes no han encontrado un bug de corrección. El objetivo declarado es una versión estable sobre TypeScript 7.1 con 100 por ciento de conformidad.

Antes de adoptarlo:

Issues abiertos, PRs cerrados. El tracker acepta reportes de bugs con una reproducción mínima; los mantenedores dicen que no tienen capacidad para revisar pull requests.
Fija la versión. Cada versión del paquete indica el commit de TypeScript que sigue, así que actualizar puede cambiar los diagnósticos.
Buen primer uso: un chequeo local o en pre-commit, o un job de CI que corra junto a tsc hasta que confíes en la salida.
Hacia dónde va: Cloudflare menciona reglas de lint con información de tipos en Oxlint, y la compilación de Rust a WebAssembly es una de las razones declaradas para elegir Rust en vez de Go: correr un toolchain de TypeScript completo en el navegador o en un Worker aislado.

¿Y tú? ¿Qué usas hoy para el type check en tu CI, y cuánto tarda?

Comenta abajo o, si este artículo te llegó por correo, responde directamente al email: tu respuesta se publica aquí.

Relacionado: bun check vs tsc: probamos el nuevo type checker de Bun en zod, playwright y hono

PHP2Shell: cómo comprobar si tu PHP es vulnerable con la skill oficial de Codex ✅ yoDEV Tested

Grego — Sun, 25 Oct 2026 15:43:50 +0000

OpenAI publicó php2shell-checker, una skill oficial de Codex que te dice si un sitio o un servidor usa una versión de PHP expuesta a PHP2Shell (CVE-2026-109618 y CVE-2026-109619) sin enviar ni una sola petición de exploit. Se instala en Codex con una instrucción, y el mismo script también funciona por su cuenta solo con Node.js.

https://github.com/openai/php2shell-checker

✅ yoDEV Tested · 21 de octubre de 2026 Ejecutamos php2shell-checker (commit 40a4746, Node.js 22.22 y PHP 8.3.6 de distribución) contra una instalación local de PHP, un servidor PHP local, un servidor parcheado simulado y un sitio público sin PHP. Los resultados que reportamos como nuestros salen de esa prueba.

¿Qué es la skill php2shell-checker de Codex?

Es un pequeño script de Node.js más dos skills de Codex, que OpenAI publicó el 21 de octubre de 2026 junto con su anuncio de Patch the Planet sobre las vulnerabilidades de PHP. OpenAI lo presenta como un PHP version checker distribuido como Codex skill, pensado para que los operadores identifiquen versiones de PHP potencialmente vulnerables.

El repositorio tiene licencia Apache-2.0 y no tiene dependencias: no hace falta npm install. Contiene tres piezas:

skills/phpcheck-url: comprueba la versión de PHP que anuncia una URL. Incluye el script real.
skills/phpcheck-server: solo instrucciones, sin script. Le indica a Codex cómo comprobar el PHP que realmente sirve un sitio cuando tienes acceso al servidor.
phpcheck.js en la raíz: un envoltorio de una línea sobre el script de la skill de URL, para que puedas ejecutarlo sin Codex.

Lo más importante es lo que no hace: nunca prueba la vulnerabilidad. Lee cadenas de versión y las compara con una tabla de versiones límite.

Al momento de publicar esta nota, el repositorio tenía 7 commits y ninguna release etiquetada (el script se identifica como 1.0.0), y OpenAI indica que no acepta contribuciones de código externas. Cambió dos veces el mismo día de su publicación, así que revisa el README antes de depender de cualquiera de los comandos de abajo.

¿Qué versión de PHP corrige PHP2Shell?

PHP 8.5.12, 8.4.27, 8.3.36 y 8.2.35, publicadas el 21 de octubre de 2026. Son exactamente un parche por encima de los límites que trae el checker (8.5.11, 8.4.26, 8.3.35 y 8.2.34), así que un servidor con cualquiera de ellas devuelve OK.

PHP 8.1 y anteriores no reciben una versión oficial. El equipo de seguridad de PHP publicó backports mínimos en código fuente para 7.4, 8.0 y 8.1, y las distribuciones Linux y los proveedores LTS recibieron los parches por adelantado. Explicamos las vulnerabilidades, las mitigaciones y las ramas sin soporte en nuestro artículo sobre PHP2Shell.

¿Cómo instalar la skill en Codex CLI?

Pídeselo a Codex dentro de una sesión:

$skill-installer install both skills from https://github.com/openai/php2shell-checker

$skill-installer es la skill integrada de Codex para añadir skills. La documentación de Codex indica que también puede descargar skills de otros repositorios, no solo del catálogo oficial. Codex detecta automáticamente las skills recién instaladas; si alguna no aparece, reinicia Codex.

Después, invoca la que corresponda a tu caso:

$phpcheck-server check the PHP version serving my site
$phpcheck-url check example.com

Usa phpcheck-server cuando tienes acceso a la máquina, y phpcheck-url cuando solo tienes una dirección.

¿Cómo comprobar la versión de PHP de una web sin Codex?

Clona el repositorio y ejecuta el script directamente. Node.js es el único requisito.

git clone https://github.com/openai/php2shell-checker
cd php2shell-checker
node phpcheck.js "https://example.com"
node phpcheck.js --local

Flags útiles: --json para obtener una salida legible por máquina, --php PATH para apuntar --local a un binario concreto y --timeout SECONDS para hosts lentos.

Un detalle con el que nos topamos: la CLI necesita una URL completa. Al pasarle un host:puerto sin esquema devolvió UNKNOWN: Invalid URL. La skill de URL lo resuelve por ti, porque sus instrucciones le piden a Codex que añada https:// a los nombres de host sin esquema.

¿Qué resultados obtuvimos al probarlo?

La batería de tests (node --test phpcheck.test.js) pasó 39 de 39. Después lo ejecutamos contra cuatro objetivos:

Objetivo	Salida	Código de salida
`--local`, PHP 8.3.6 de distribución	`VULNERABLE: PHP 8.3.6`	1
Servidor local `php -S` con PHP 8.3.6	`VULNERABLE: PHP 8.3.6`	1
Servidor local que envía `X-Powered-By: PHP/8.3.36`	`OK: PHP 8.3.36`	0
github.com (sin cabecera de PHP)	`UNKNOWN` — "PHP version not found"	3

Con --json, la comprobación local devolvió:

{"patch_status":"vulnerable","php_version":"8.3.6","reason":"PHP 8.3.6","exit_code":1}

La primera fila es la más instructiva. Ese PHP 8.3.6 viene de los paquetes de la distribución, y las distribuciones suelen aplicar backports de seguridad sin cambiar el número de versión upstream. El checker no puede verlo. En nuestro caso tenía razón al alertar, porque la compilación es anterior a la corrección, pero con un paquete de distribución ya parcheado diría exactamente lo mismo.

¿Qué significan OK, VULNERABLE y UNKNOWN?

Significan menos de lo que parece, y el README lo deja claro.

OK (código 0): la versión está por encima del límite de su rama. Es una comparación de versiones, no una verificación de la corrección. Las cabeceras se pueden reescribir, y un OK obtenido de una cabecera puesta a mano no vale nada: así es exactamente como conseguimos nuestra fila OK.
VULNERABLE (código 1): la versión es igual o inferior al límite. Si usas paquetes de distribución, confírmalo con el aviso de seguridad de tu proveedor antes de alarmarte. En 8.1 y anteriores seguirá diciendo VULNERABLE aunque apliques un backport en código fuente, porque la cadena de versión no cambia.
UNKNOWN (código 3): no encontró versión, la rama no está en la tabla o es una compilación previa a una versión estable. No significa que esté parcheado. Cualquier sitio que oculte X-Powered-By, una medida de hardening habitual, cae aquí. También las release candidates de PHP 8.6, porque la rama 8.6 no está en la tabla, aunque 8.6.0 RC4 ya incluye la corrección.

Los argumentos inválidos devuelven el código 2. Los códigos 1 y 3 son resultados, no fallos de ejecución: útil si lo integras en CI o en un script de monitoreo.

¿Por qué no basta con revisar la URL?

Porque solo ve lo que el servidor decide anunciar. El modo URL lee las cabeceras X-Powered-By y Server, envía una petición HEAD (y recurre a GET solo si recibe un 405 o un 501), no sigue redirecciones y no lee el cuerpo de la página.

Eso lo convierte en una herramienta rápida de triaje para una lista de sitios, no en una prueba. La skill phpcheck-server existe para la comprobación más sólida: le indica a Codex que empiece con php -v, pero que confirme que la CLI coincide con la compilación de PHP-FPM o Apache que realmente sirve el sitio, y que compare la revisión completa del paquete con los avisos de PHP o del proveedor. Si no puede verificar la versión que sirve el sitio, la instrucción es reportar desconocido.

Ambas skills incluyen la misma regla: no ejecutar pruebas de exploit.

¿Por qué importa que sea una skill de Codex?

Es la primera vez que vemos a OpenAI publicar una skill oficial de Codex como repositorio independiente ligado a una respuesta de seguridad, en lugar de incluirla en su catálogo de skills o en su documentación. La skill es el mecanismo de distribución: una sola instrucción pone un checker revisado dentro del agente de cada usuario de Codex, con las salvaguardas ("no ejecutar pruebas de exploit") escritas en la propia skill.

Para quien busque en inglés: son Codex skills que funcionan en Codex CLI, y el patrón de instalación con $skill-installer sirve igual para cualquier otro repositorio de skills.

El mismo anuncio compromete suscripciones para mantenedores de código abierto a través de Codex for OSS. No pudimos confirmar cuándo se abrió ese programa, así que la noticia de hoy es la skill, no la suscripción.

¿Y tú? ¿Cuántos servidores PHP tienes que revisar esta semana?

Comenta abajo o, si este artículo te llegó por correo, responde directamente al email: tu respuesta se publica aquí.

Relacionado: CVE-2026-109618 y CVE-2026-109619: qué versión de PHP necesitas y cuándo sale el parche

TokenEconomizer: el Plugin de Microsoft para Claude Code, Codex y Copilot CLI que Recortó un 31 por ciento del Contexto ✅ yoDEV Tested

Grego — Sun, 25 Oct 2026 15:38:52 +0000

TokenEconomizer, el plugin de Microsoft Research y UC Berkeley para Claude Code, Codex, GitHub Copilot CLI y Pi, recortó un 31 por ciento del contexto de cada petición de Claude Code en nuestra prueba, sin perder ninguna tarea. No actúa desde la primera sesión: necesita varias sesiones en el mismo repositorio antes de empezar a ahorrar.

https://github.com/microsoft/TokenEconomizer

✅ yoDEV Tested · 23 de octubre de 2026

Ejecutamos 32 sesiones de Claude Code 2.1.305 con Sonnet, con y sin TokenEconomizer (commit 0ce0e06), sobre 8 tareas seguidas en un mismo repositorio de Python, repetidas dos veces. Los resultados que reportamos como nuestros salen de esa prueba.

¿Qué es TokenEconomizer y cómo ahorra tokens?

Es un plugin que no toca tu agente y abarata las sesiones siguientes en el mismo repositorio. En cada turno, un agente de programación vuelve a cobrar sus instrucciones, todas las herramientas cargadas y la conversación hasta ese punto. El plugin lee cada sesión terminada y cambia lo que pagan las siguientes con tres mecanismos:

Micro-skills. Los datos del entorno que tus sesiones redescubren fallando una y otra vez (por ejemplo, que pytest no está instalado pero python -m pytest sí funciona) se aprenden y se indican al inicio de la sesión siguiente. Aprenderlos no consume ninguna llamada al modelo.
Poda de herramientas (tool pruning). Las herramientas que siguen cargadas pero nadie usa, por defecto durante cinco sesiones seguidas, se dejan fuera de las sesiones siguientes a través de la propia configuración del agente.
Guardián de bucles (loop guard). Un turno que repite el mismo ciclo fallido de editar y probar recibe una redirección. Si sigue atascado, el plugin te dice cómo detenerlo. Nunca detiene un turno por su cuenta.

Usa solo la biblioteca estándar de Python, no necesita una API key propia y funciona con el plan o el inicio de sesión que ya use tu agente. Lo que aprende se guarda en ~/.tokeneconomizer. Licencia Apache 2.0.

¿Cuánto ahorra según el paper de Microsoft?

El paper (arXiv 2610.22732, publicado el 15 de octubre de 2026) reporta un costo medio entre un 18,4 y un 30,9 por ciento más bajo en SWE-Bench, con cinco combinaciones de agente y modelo. Los autores miden teniendo en cuenta la caché de prompts e incluyen las llamadas del propio plugin:

Agente y modelo	Costo medio más bajo
Claude Code + Opus 4.8	30,9%
Codex + GPT-5.6 Sol	26,1%
Codex + GPT-5.6 Terra	24,7%
Claude Code + Sonnet 5	23,6%
Copilot CLI + Sonnet 5	18,4%

Según el paper, el Pass@1 subió en 4 de las 5 combinaciones. Son cifras de los propios autores, medidas sobre 277 tareas en seis repositorios, con las tareas de cada repositorio en secuencia: una racha mucho más larga que una semana normal de trabajo.

¿Cuánto ahorró en nuestra prueba con Claude Code?

Armamos un pequeño repositorio de Python con dos trampas que cada sesión tiene que redescubrir: los imports solo funcionan con PYTHONPATH=src, y el paquete se niega a cargar si no está definida TIENDA_ENV. No documentamos ninguna de las dos, a propósito. Después le dimos a Claude Code 8 reportes de bugs seguidos, con y sin el plugin, dos veces.

	Sin plugin	Con plugin
Tareas resueltas	16/16	16/16
Contexto por petición, antes de que el plugin actuara	24.779 tokens	24.809 tokens
Contexto por petición, con la poda activa	25.966 tokens	17.795 tokens (−31%)
Costo de las sesiones con la poda activa	0,72 USD	0,61 USD (−15%)

Qué hizo cada mecanismo:

La poda de herramientas actuó, y su efecto fue claro. Se activó en la sesión 8 de la primera tanda y en la sesión 6 de la segunda. Dejó fuera 284 herramientas: la mayoría eran de conectores que se cargan en cada sesión de nuestra configuración (Docs, Discourse, Drive), más 16 herramientas propias de Claude Code que nunca usamos, como las tareas programadas y los worktrees. Desde ese momento, cada petición llevaba unos 8.000 tokens menos.
Las micro-skills no llegaron a activarse. El plugin sí detectó que nuestras sesiones fallaban con python -m pytest. Pero un dato solo se forma tras tres sesiones que lo confirman entre al menos cuatro donde aplica, y Claude no falló de la misma forma con suficiente constancia. Tras 8 sesiones, el mejor candidato iba en 2 de 7.
El guardián de bucles no intervino. Ningún turno se atascó: las tareas eran cortas.

El costo propio del plugin fue cero. En las 32 sesiones, el lado con plugin costó un 8,5 por ciento menos, pero la mayor parte vino de sesiones en las que todavía no había cambiado nada. Esa parte es variación normal entre ejecuciones, así que no la contamos como efecto del plugin. Las 4 sesiones con poda activa son una muestra pequeña; el dato sólido es la caída del contexto.

Cambiamos un ajuste respecto de los valores por defecto. Normalmente, la poda espera a que tus sesiones lleven una hora inactivas antes de escribir la lista de herramientas excluidas, para no romper una caché de prompts que sigue caliente. Nuestras sesiones iban una detrás de otra, así que usamos toolprune_quiet_minutes=0.

¿Te conviene si usas muchos servidores MCP en Claude Code?

Sí: es el caso en que más ahorra. El ahorro depende de dos cosas:

Cuántas herramientas se cargan en cada sesión. Si tienes muchos servidores MCP o conectores, la poda tiene mucho que quitar. Con una configuración mínima, hay poco que recortar.
Cuántas sesiones haces en el mismo repositorio. Los datos se forman a partir de evidencia repetida, así que el plugin rinde en un código que trabajas a diario, no en repos de una sola vez. Si tu repositorio ya documenta sus particularidades en un CLAUDE.md, las micro-skills tienen menos que aprender.

Si quieres recortar tokens por otras vías, aquí probamos cómo hacerlo con hooks, y aquí cómo ver el consumo de tokens en Codex CLI.

¿Es gratis y cuánto baja el precio de Claude Code?

El plugin es gratis y open source, y no hace llamadas al modelo por su cuenta: sus ayudantes de pago (un generador de datos con LLM y un juez para el guardián de bucles) vienen apagados salvo que actives paid=true. Lo que baja es lo que pagas por cada sesión de tu agente: en nuestra prueba, un 15 por ciento en las sesiones con la poda activa, a precios de lista de la API. Con un plan de suscripción, el efecto es que la misma cuota te alcanza para más trabajo.

¿Cómo instalar el plugin en Claude Code, Codex y Copilot CLI?

Necesitas Python 3.10 o superior en el PATH. Clona el repositorio en una carpeta donde vaya a quedarse, porque los agentes ejecutan el plugin desde ahí:

Claude Code

git clone https://github.com/microsoft/TokenEconomizer.git
claude plugin marketplace add "$PWD/TokenEconomizer"
claude plugin install tokeneconomizer@tokeneconomizer

Inicia claude en un repositorio y ejecuta /tokeneconomizer:status. Una vez por máquina, y de nuevo cada vez que Claude Code se actualice, ejecuta /tokeneconomizer:toolprune refresh-catalog: registra qué herramientas carga una sesión, y sin ese paso la poda solo ve unas pocas.

Codex

codex plugin marketplace add "$PWD/TokenEconomizer"
codex plugin add tokeneconomizer@tokeneconomizer

Cuando Codex muestre Hooks need review, elige Trust all and continue.

Copilot CLI

copilot plugin marketplace add "$PWD/TokenEconomizer"
copilot plugin install tokeneconomizer@tokeneconomizer

La ruta del marketplace tiene que ser absoluta. Versiones soportadas según el README: Claude Code de la 2.1.300 a la 2.1.307, Codex de la 0.153.1 a la 0.163.0 y Copilot CLI de la 1.0.83 a la 1.0.102. Al momento de publicar esta nota, los autores no habían comprobado versiones posteriores.

¿Cómo ver lo que hizo o deshacer los cambios?

Desde una terminal, dentro del repositorio y sin gastar tokens:

~/.tokeneconomizer/bin/te status              # qué aprendió y cuánto costaron tus sesiones
~/.tokeneconomizer/bin/te toolprune           # qué herramientas dejó fuera y por qué
~/.tokeneconomizer/bin/te toolprune restore   # devolverlas

Por defecto, la poda se aplica sin preguntarte, y en Claude Code el aviso solo aparece en la transcripción detallada (Ctrl+O). Si prefieres aprobar cada lista tú mismo, ejecuta te config set toolprune=propose. Para una sola sesión sin el plugin, inicia el agente con TE_DISABLE=1 claude.

¿Y tú? ¿Cuántos servidores MCP tienes conectados hoy en tu agente de programación?

Comenta abajo o, si este artículo te llegó por correo, responde directamente al email: tu respuesta se publica aquí.

Relacionado: Cómo reducir el consumo de tokens de tu agente de IA: probamos Pensieve en un repo real

¿Cómo hacer migraciones de esquema en ClickHouse? Probamos chkit, el Drizzle que le faltaba ✅ yoDEV Tested

Grego — Sun, 25 Oct 2026 15:32:37 +0000

Para hacer migraciones de esquema en ClickHouse con chkit, declaras tus tablas en TypeScript o Python, chkit genera el SQL de la migración a partir del diff, lo aplica y hace fallar tu CI si la base en vivo se desvía de lo declarado. Probamos la versión 0.2.0-beta.11 de punta a punta, incluidas las partes que deben fallar.

https://github.com/obsessiondb/chkit

✅ yoDEV Tested · 22 de octubre de 2026 Probamos chkit 0.2.0-beta.11 (TypeScript con Bun) y chkit-py 0.2.0 contra clickhouse-server 26.9.25.15 en Linux. Los resultados que reportamos como nuestros salen de esa prueba.

¿Qué es chkit?

chkit es schema as code para ClickHouse, con licencia MIT: describes tablas, vistas, vistas materializadas y diccionarios en código, y la CLI calcula los CREATE y ALTER necesarios. En su Show HN se presenta como "like Drizzle", y el flujo tiene esa forma: un archivo de esquema, un paso generate que escribe SQL que puedes leer, un paso migrate que lo aplica y una tabla de registro que guarda qué se ejecutó.

Se distribuye en varios paquetes de npm: chkit (la CLI), @chkit/core (el DSL de esquema, la configuración y el motor de diff) y plugins para importar un esquema existente, generar tipos y hacer backfills. También hay una versión para Python, chkit-py.

Dos cosas que debes saber antes de adoptarlo.

Está en beta. El README afirma que la CLI y el DSL de esquema son estables y que chkit ya corre cargas de producción, pero el equipo se reserva pequeños cambios incompatibles en la experiencia de uso y en las APIs internas antes de la 1.0. Todo lo que ves en este artículo está fijado a 0.2.0-beta.11, publicada en npm el 12 de octubre de 2026.

Lo construye un proveedor. chkit viene del equipo de ObsessionDB, un servicio de ClickHouse administrado, y el README recomienda ObsessionDB para producción. La herramienta en sí es MIT y funciona con cualquier ClickHouse. La relación se nota en chkit init, que te ofrece registrarte en ObsessionDB antes de explicarte cómo conectar tu propio servidor.

¿Cómo se instala chkit?

Con Bun, fijando la versión que probamos (el comando del README es el mismo sin las versiones @):

bun add -d chkit@0.2.0-beta.11 @chkit/core@0.2.0-beta.11
bunx chkit init

init crea clickhouse.config.ts y un esquema de ejemplo en src/db/schema/example.ts. La configuración generada lee la conexión de cuatro variables de entorno y solo define el bloque clickhouse cuando CLICKHOUSE_URL está definida:

export CLICKHOUSE_URL=http://localhost:8123
export CLICKHOUSE_USER=default
export CLICKHOUSE_PASSWORD=
export CLICKHOUSE_DB=default

Las cuatro tienen que estar definidas; una contraseña vacía está permitida, una sin definir no. El esquema de ejemplo además se niega a cargar sin CLICKHOUSE_DB, así que una terminal mal configurada falla de forma visible en lugar de generar migraciones para la base equivocada.

Para Python es pip install chkit-py, y el comando sigue siendo chkit. Más abajo verás en qué se diferencia.

¿Cómo se define el esquema de base de datos de ClickHouse en TypeScript?

Se define con la función table() de @chkit/core. Esta es la tabla que genera init:

import { schema, table } from '@chkit/core'

const database = process.env.CLICKHOUSE_DB
if (!database?.trim()) {
  throw new Error('Set CLICKHOUSE_DB to the intended database before generating migrations.')
}

const events = table({
  database,
  name: 'events',
  engine: 'MergeTree',
  columns: [
    { name: 'id', type: 'UInt64' },
    { name: 'source', type: 'String' },
    { name: 'ingested_at', type: 'DateTime64(3)', default: { expression: 'now64(3)' } },
  ],
  primaryKey: ['id'],
  orderBy: ['id'],
  partitionBy: 'toYYYYMM(ingested_at)',
})

export default schema(events)

Los tipos de columna son los propios de ClickHouse escritos como texto, así que no hay una capa de traducción de tipos que aprender. Un detalle que nos sorprendió: un default escrito como texto plano es un valor literal. En nuestra primera prueba escribimos default: "''" para un valor vacío y obtuvimos DEFAULT '''''', es decir, el texto de dos caracteres ''. Las expresiones van en { expression: '...' } (la forma antigua del README, 'fn:now64(3)', sigue funcionando y es equivalente). La referencia del DSL lo documenta, y generate rechaza el error más común: una llamada a función escrita como texto, como 'now64(3)', en una columna que no puede guardar texto.

¿Cómo hacer migraciones de esquema en ClickHouse?

Ejecuta generate con un nombre y luego migrate:

bunx chkit generate --name init
bunx chkit migrate --apply
bunx chkit status

generate escribe un archivo SQL con marca de tiempo en chkit/migrations/ y actualiza chkit/meta/snapshot.json. Este es el archivo que obtuvimos:

-- chkit-migration-format: v1
-- generated-at: 2026-10-23T00:17:16.148Z
-- cli-version: 0.2.0-beta.11
-- definition-count: 1
-- operation-count: 2
-- rename-suggestion-count: 0
-- risk-summary: safe=2, caution=0, danger=0

-- operation: create_database key=database:default risk=safe
CREATE DATABASE IF NOT EXISTS default;

-- operation: create_table key=table:default.events risk=safe
CREATE TABLE IF NOT EXISTS default.events
(
  `id` UInt64,
  `source` String,
  `ingested_at` DateTime64(3) DEFAULT now64(3)
) ENGINE = MergeTree()
PARTITION BY toYYYYMM(ingested_at)
PRIMARY KEY (`id`)
ORDER BY (`id`);

Cada sentencia lleva una etiqueta de riesgo, y el SQL es DDL normal de ClickHouse que puedes revisar en un pull request. migrate --apply lo ejecutó y lo registró en la tabla _chkit_migrations, con el nombre del archivo, un checksum SHA-256 del archivo y la versión de chkit que lo aplicó.

Agregar una columna al esquema y ejecutar generate --name add-country produjo una sola sentencia:

-- operation: alter_table_add_column key=table:default.events:column:country risk=safe
ALTER TABLE default.events ADD COLUMN IF NOT EXISTS `country` LowCardinality(String);

¿Cómo detectar schema drift en ClickHouse?

Con chkit drift, que inspecciona la base en vivo y la compara con el snapshot. Para probarlo hicimos lo que alguien siempre termina haciendo: agregar una columna a mano, por fuera de chkit.

ALTER TABLE default.events ADD COLUMN debug_flag UInt8

chkit drift la detectó:

Expected objects: 1
Actual objects:   1
Drifted:          yes

Table shape drift:
- default.events
  extraColumns=debug_flag
  reasonCodes=extra_column

Con --json devuelve lo mismo de forma estructurada, con una entrada tableDrift por tabla y un código de motivo para cada tipo de diferencia: columnas que faltan o sobran, tipos o valores por defecto cambiados, settings, índices, TTL, motor, clave primaria, ORDER BY, PARTITION BY y proyecciones.

Ojo: drift siempre termina con código 0. Informa, no bloquea. El comando que hace fallar un build es chkit check.

Las tablas que chkit no administra se tratan distinto. Creamos a mano una tabla scratch, y drift la listó como objeto inesperado pero igual indicó Drifted: no, y check pasó. Es a propósito: chkit puede compartir una base con tablas que no le pertenecen. Si chkit es dueño de toda la base, la política check.failOnExtraObjects hace que los objetos sobrantes también fallen.

¿Cómo usar chkit check en CI con GitHub Actions?

chkit check termina con código 1 si hay migraciones pendientes, si alguien editó un archivo de migración ya aplicado o si el esquema en vivo se desvió. Provocamos los tres casos:

Tras agregar la columna country pero antes de migrar: Failed checks: pending_migrations, schema_drift, código 1.
Después de migrar: Check status: ok, código 0.
Tras la columna debug_flag agregada a mano: Failed checks: schema_drift, código 1.
Tras agregar una línea a un archivo de migración ya aplicado: Failed checks: checksum_mismatch, código 1. chkit status nombró el archivo; revertir el cambio lo resolvió.

El workflow de GitHub Actions para pull requests que trae la documentación es:

name: Schema Validation
on: pull_request

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: '1.3.5'

      - run: bun install --frozen-lockfile

      - name: Check schema consistency
        run: bunx chkit check --strict --json

      - name: Verify generated types
        run: bunx chkit codegen --check --json

--strict activa todas las políticas sin importar el archivo de configuración, que es lo que quieres en CI. Un requisito que el ejemplo no muestra: check necesita llegar a un servidor ClickHouse, porque el registro de migraciones vive ahí. Sin conexión se detiene con "clickhouse config is required for check". El ejemplo de despliegue de la misma guía pasa CLICKHOUSE_URL, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD y CLICKHOUSE_DB desde los secrets; el job de validación también los necesita.

¿Qué hace chkit con las migraciones destructivas?

Las bloquea, salvo que digas lo contrario. Quitamos la columna source del esquema y generate escribió:

-- operation: alter_table_drop_column key=table:default.events:column:source risk=danger
ALTER TABLE default.events DROP COLUMN IF EXISTS `source`;

Al ejecutar migrate --apply sin terminal, como en CI, se negó con un código de advertencia (drop_column_irreversible), el motivo, el impacto y una recomendación, y nos pidió repetir con --allow-destructive. Con esa opción, se aplicó.

Una diferencia con la documentación: dice que una migración destructiva bloqueada termina con código 3 en ejecuciones no interactivas. En nuestras pruebas terminó con 3 solo con --json; en modo texto, con la entrada cerrada y también con CI=true, terminó con 1. Ambos hacen fallar el job, así que nada se cuela, pero si tu pipeline separa el código 3 para mandar los cambios destructivos a un job con aprobación manual, como sugiere la documentación, usa --json.

¿chkit genera tipos de TypeScript desde las tablas de ClickHouse?

Sí, con @chkit/plugin-codegen. Con el plugin registrado en clickhouse.config.ts (codegen({ outFile: './src/generated/chkit-types.ts' })), chkit codegen escribió:

export type DefaultEventsRow = {
  id: string
  country: string
  ingested_at: string
}

UInt64 y DateTime64 salen como string, que coincide con cómo ClickHouse los devuelve en JSON. El plugin también puede generar esquemas de Zod, y chkit codegen --check hace fallar el CI cuando el archivo generado quedó desactualizado.

¿Funciona chkit con Python?

Sí, con una diferencia que conviene conocer. pip install chkit-py instala la versión 0.2.0, que la documentación marca como alfa. init, generate, migrate --apply y check funcionaron en nuestra prueba.

La diferencia está en el drift. Por defecto, chkit drift en Python compara el snapshot con tus archivos de esquema locales, no con la base en vivo. Tras agregar la misma columna a mano, drift en Python indicó Drifted: no, y chkit check --strict terminó con código 0. Al agregar --live, ambos la detectaron: drift --live reportó extra_column y check --live falló con schema_drift, código 1.

Al 22 de octubre de 2026, --live solo aparece en la página de Kafka de la documentación, y el workflow de Python de la guía de CI ejecuta chkit check --strict --json sin esa opción, mientras afirma que las opciones son las mismas que en TypeScript. Si usas la versión de Python en CI, agrega --live.

¿Es chkit como Drizzle ORM?

En el flujo de trabajo, sí; en el alcance, no. Drizzle ORM es el ORM de TypeScript con el que muchos equipos definen su esquema y generan migraciones para bases relacionales. chkit copia ese ciclo (esquema en código, generate, migrate) y lo lleva a ClickHouse, pero no es un ORM: no construye consultas desde tu código. Si tu equipo ya escribe el esquema de Postgres en Drizzle y el DDL de ClickHouse es lo único que sigue a mano, ese es el hueco que llena.

¿Qué otras herramientas de migración de base de datos hay para ClickHouse?

La propia base de conocimiento de ClickHouse lista una docena. La mayoría son ejecutores imperativos que aplican archivos SQL versionados en orden: golang-migrate, Goose, Flyway, Liquibase y ejecutores específicos de ClickHouse para Node.js y Python. Atlas y Ptah son declarativos como chkit y también detectan drift.

Lo que aporta chkit es el enfoque centrado en TypeScript: el esquema vive en el mismo lenguaje que tu aplicación, los tipos se generan a partir de él y una sola CLI cubre generate, migrate, drift y la validación en CI. Y si lo que buscas es explorar esa base desde el navegador, ya vimos cómo desplegar LibreDB Studio con Docker o Helm.

¿Vale la pena usar chkit?

Si usas ClickHouse junto a un código en TypeScript y tus cambios de esquema hoy viven en archivos SQL sueltos o en la memoria de alguien, chkit merece una tarde. El SQL generado se lee bien, la protección contra cambios destructivos funciona y la detección de drift encontró una columna agregada a mano que de otra forma habría pasado desapercibida.

Fija la versión, porque la 1.0 todavía puede traer pequeños cambios incompatibles. Y si trabajas en Python, trata esa versión como la alfa que dice ser y usa --live.

¿Y tú? ¿Qué cambio de esquema hecho a mano en producción te costó más descubrir?

Comenta abajo o, si este artículo te llegó por correo, responde directamente al email: tu respuesta se publica aquí.

Relacionado: Alternativa a DBeaver en el navegador: cómo desplegar LibreDB Studio con Docker o Helm

earstrip vs earcut: probamos la triangulación de 3,7 millones de polígonos de OpenStreetMap ✅ yoDEV Tested

Grego — Sun, 25 Oct 2026 15:25:56 +0000

earstrip es un reemplazo directo de earcut para la triangulación de polígonos en WebGL. En nuestra prueba fue unas 6 veces más rápido con polígonos con miles de huecos, y dibujó mucho mejor los polígonos rotos. Con polígonos de mapa comunes, en x86, la ventaja fue de apenas 1,1–1,2 veces, lejos de las cifras que el autor midió en Apple silicon.

https://github.com/GLMap/earstrip

✅ yoDEV Tested · 23 de octubre de 2026 Corrimos earstrip 0.2.0 contra earcut 3.2.4 (npm) y earcut.hpp 3.2.4 (C++) sobre los 5,7 millones de polígonos de OpenStreetMap que publica el autor, en una VM x86 con Intel Xeon, Node 22, 24 y 26, GCC 13 y Clang 18. Los resultados que reportamos como nuestros salen de esa prueba.

¿Qué es la triangulación de polígonos y para qué sirven earcut y earstrip?

La triangulación de polígonos convierte cualquier contorno en un conjunto de triángulos, que es lo único que una GPU sabe rellenar. Cada edificio, parque o lago que dibuja un mapa web o una escena en WebGL pasa primero por ese paso. earcut, de Mapbox, es la librería que usa la mayoría de los stacks de mapas web para hacerlo: le pasas las coordenadas planas y los índices donde empieza cada hueco, y te devuelve tres índices de vértice por triángulo.

earstrip es el triangulador del motor de mapas móviles GLMap. Globus Software lo publicó como librería independiente el 16 de octubre de 2026 y viene en dos formatos:

un único archivo de cabecera C++17 (header-only);
un build de WebAssembly en npm cuya llamada principal recibe exactamente los mismos argumentos que earcut.

Se diferencia de earcut en dos puntos:

Triangle strips. Recorta las "orejas" del polígono (ear clipping) siguiendo tiras en zigzag, así que su salida nativa necesita unos 1,7 índices por triángulo en lugar de 3.
Anillos rotos. Cuando los anillos de un polígono se cruzan o se tocan, recurre a una triangulación de Delaunay restringida (constrained Delaunay) en lugar de devolver los triángulos que hayan quedado.

La licencia es ISC, la misma que la de earcut.

¿Cómo reemplazar earcut por earstrip?

Instalas el paquete y cambias el import; ese es todo el diff:

npm install earstrip

- import earcut from 'earcut';
+ import earstrip from 'earstrip';

- const triangles = earcut(vertices, holes, dimensions);
+ const triangles = earstrip(vertices, holes, dimensions);

Si tus datos vienen en GeoJSON, earstrip trae su propio flatten(). En nuestra prueba su salida fue idéntica a la del flatten() de earcut:

import earstrip, { flatten } from 'earstrip';

const { vertices, holes, dimensions } = flatten(geojsonPolygon.coordinates);
const triangles = earstrip(vertices, holes, dimensions);

Tres notas prácticas de la prueba:

Formato del módulo. El paquete es solo ESM. En Node 22, require('earstrip') igual nos funcionó gracias al soporte require(esm) de Node.
Carga. El módulo WebAssembly viene incrustado y compila de forma síncrona donde la plataforma lo permite. Donde no, el README indica hacer await ready antes de la primera llamada (import { ready } from 'earstrip').
C++. Copia include/earstrip.hpp a tu proyecto. Necesita C++17 y nada más que la biblioteca estándar. La suite de tests en C++ del repositorio pasó completa en nuestra máquina.

¿earstrip es más rápido que earcut?

Depende de tus polígonos y de la máquina. Usamos los datos de benchmark del propio autor, con los checksums verificados: extractos de OpenStreetMap del voivodato de Mazovia (Polonia) y las teselas del mapa mundial de GLMap. El harness fue nuestro, contra los paquetes de npm, con un hilo y el mejor de 5 corridas.

Prueba	Autor (Apple M4 Pro)	yoDEV (x86 Xeon)
3,74 M polígonos de mapa, llamada drop-in, V8	1,44× más rápido	1,08–1,19× más rápido
Igual, la API más rápida (`direct.batch`)	1,74× más rápido	1,21–1,38× más rápido
56 mil polígonos del mapa mundial, hasta 11.674 huecos en uno	7,4× más rápido	5,6–6,0× más rápido
C++ nativo vs earcut.hpp, 3,74 M polígonos	13% más rápido	GCC 13: empate · Clang 18: 12% más rápido
C++ nativo, mapa mundial	6,3× más rápido	4,0× más rápido (GCC 13)

Con polígonos con muchos huecos, la promesa se cumple. En el set mundial, earcut necesitó unos 10,2 segundos en Node y earstrip entre 1,7 y 1,9. Es justo el caso donde earcut paga caro por unir cada hueco al contorno, y earstrip manda directo a su ruta de Delaunay los polígonos con más de 128 anillos.

Con polígonos de mapa comunes, la ganancia es mucho menor. En nuestra máquina x86 la llamada drop-in fue entre 8 y 19 por ciento más rápida en Node 22, 24 y 26. El README reporta 44 por ciento para V8 en un M4 Pro.

En C++ nativo, depende del compilador. Hubo empate con GCC y una ventaja de 12 por ciento con Clang, así que la ventaja con datos cotidianos parece sensible al compilador y a la CPU. No investigamos por qué; reportamos lo que medimos.

Si tus datos se parecen a los nuestros y la velocidad es tu motivo para cambiar, haz un benchmark primero en el hardware donde realmente corre tu código.

¿Qué pasa con los polígonos que se cruzan a sí mismos?

earstrip los dibuja bien, y esta parte de lo que promete el autor se reprodujo con exactitud. Los datos de mapa redondeados a una grilla de teselas suelen terminar con anillos que se cruzan o se tocan, y el ear clipping asume que eso no pasa. El set principal tiene 82 polígonos que las orejas no pueden cortar de forma exacta. En ellos, los triángulos de earstrip se alejaron del relleno correcto (even-odd) en un 0,15 por ciento de los píxeles en promedio, y los de earcut.hpp en un 30,7 por ciento. El autor reporta 0,15 y 31.

Un ejemplo mínimo muestra la diferencia. Toma un polígono en forma de corbatín que se cruza a sí mismo ([0,0, 10,10, 10,0, 0,10]):

earcut devolvió un solo triángulo y rellenó solo uno de los dos lóbulos.
earstrip devolvió dos triángulos que cubren ambos, y lastStatus() informó approximate.

Ese estado le permite a tu código saber cómo se resolvió cada polígono. Los valores posibles son exact, constrained, holes-left-out, approximate y refused. En el set de 3,74 millones de polígonos, todos salvo 82 volvieron como exact.

¿Qué son los triangle strips y los necesitas en WebGL?

Un triangle strip es una lista de índices donde cada índice nuevo forma un triángulo con los dos anteriores. La GPU dibuja n triángulos con unos n + 2 índices en lugar de 3n. earstrip escribe tiras de forma nativa:

1,66 índices por triángulo tanto en el set principal como en el mundial, contra 3 de una lista de triángulos normal;
1,95 en un set de polígonos casi todos pequeños y simples, donde la ganancia es menor.

La llamada drop-in earstrip() vuelve a convertir las tiras en una lista de triángulos al estilo earcut, así que ese ahorro solo lo obtienes con las otras APIs:

strips() devuelve las tiras tal cual.
Las llamadas direct escriben el polígono directamente en la memoria de WebAssembly y devuelven un solo index buffer listo para TRIANGLE_STRIP en WebGL 2 o WebGPU. Esa ruta fue además la más rápida en nuestro benchmark.

import { strips } from 'earstrip';

const { indices, ends, clockwise } = strips(vertices, holes);

¿Conviene cambiar de earcut a earstrip?

Cámbiate si:

Tus datos tienen polígonos con muchos huecos (costas, bosques con claros, teselas mundiales). La aceleración de 5 a 6 veces se reprodujo.
Renderizas datos de mapa reales que pueden traer anillos que se cruzan o se tocan, y ya has visto errores de relleno.
Controlas el index buffer y puedes usar tiras en WebGL 2 o WebGPU.

Piénsalo dos veces si:

Tus polígonos son pequeños y simples y la velocidad es tu único motivo. En x86 la ganancia que medimos fue modesta.
El tamaño del bundle importa. Tal como se publica, el JavaScript de earstrip más su WebAssembly incrustado sumó unos 41 KB con gzip, frente a unos 13 KB del código fuente de earcut sin minificar. La cifra de 27 KB del README corresponde solo al binario WebAssembly.
Necesitas una API estable. Al momento de publicar esta nota (23 de octubre de 2026), earstrip está en la versión 0.2.0, publicada tres días antes. Considera estable la llamada compatible con earcut; el resto puede cambiar antes de la 1.0.

¿Y tú? ¿Qué librería usas hoy para triangular polígonos en tu stack de mapas o WebGL?

Comenta abajo o, si este artículo te llegó por correo, responde directamente al email: tu respuesta se publica aquí.

Relacionado: Node:ffi en Node.js 26.9: cómo llamar a una librería de C sin compilar un addon nativo

RAG-Anything: Cómo Hacer RAG con PDFs que Tienen Imágenes, Tablas y Ecuaciones

Grego — Sun, 25 Oct 2026 15:20:53 +0000

RAG-Anything es un framework open source en Python para chatear con tus PDFs y documentos de Office sin perder sus imágenes, tablas ni ecuaciones. En lugar de aplanar el archivo a texto plano, separa cada elemento, lo describe con un modelo de lenguaje o de visión y lo conecta todo en un grafo de conocimiento que puedes consultar en lenguaje natural. Lo desarrolla HKUDS, el laboratorio de la Universidad de Hong Kong detrás de LightRAG, tiene licencia MIT y supera las 24.100 estrellas en GitHub.

https://github.com/HKUDS/RAG-Anything

¿Qué es RAG-Anything?

RAG-Anything es un pipeline de RAG multimodal (multimodal RAG) construido sobre LightRAG. Cubre todo el recorrido, desde la ingesta del documento hasta la respuesta, en cuatro etapas:

Parsing. Un parser divide el archivo en bloques de texto, imágenes, tablas y ecuaciones, y registra la página de la que viene cada uno.
Análisis por tipo. Cada elemento pasa por su propio procesador. Un modelo de visión escribe descripciones de las imágenes teniendo en cuenta el contexto, las tablas se interpretan como datos estructurados y las ecuaciones se procesan en LaTeX.
Grafo de conocimiento. Los elementos se convierten en entidades relacionadas con el texto que los rodea. Una cadena de relaciones belongs_to conserva la jerarquía de secciones del documento.
Recuperación híbrida. Las consultas combinan búsqueda vectorial con recorrido del grafo, así que una respuesta puede traer un párrafo junto con el gráfico que lo explica. Es la idea detrás del knowledge graph RAG o graph RAG, extendida a contenido que no es texto.

Acepta PDFs, documentos de Office (DOC, DOCX, PPT, PPTX, XLS, XLSX), imágenes (JPG, PNG, BMP, TIFF, GIF, WebP) y archivos de texto (TXT, MD). Las versiones recientes también aceptan audio y video, que vemos más abajo.

¿Por qué el RAG tradicional falla con PDFs que tienen tablas y gráficos?

Porque un pipeline de RAG típico extrae la capa de texto del PDF, la corta en fragmentos y genera embeddings de esos fragmentos. Todo lo que no es texto corrido se pierde por el camino:

Un gráfico de barras desaparece.
Una tabla se convierte en una lista de números sin los encabezados de sus columnas.
Una fórmula queda como caracteres rotos.

En documentación técnica, reportes financieros y papers de investigación, la respuesta suele estar justo ahí.

RAG-Anything trata esos elementos como contenido de primera clase. Un gráfico lo describe un modelo de visión y se guarda como una entidad vinculada al párrafo que lo menciona. Una tabla conserva su estructura y su leyenda.

El enfoque está descrito en el reporte técnico de los autores en arXiv (2510.12323, octubre de 2025). Según los propios autores, supera a los métodos existentes en benchmarks multimodales, con las mayores ventajas en documentos largos. Son resultados reportados por el equipo que creó la herramienta, y el reporte es un preprint.

¿Qué diferencia hay entre LightRAG y RAG-Anything?

LightRAG es el motor y RAG-Anything es la capa multimodal que va encima. LightRAG aporta la indexación basada en grafos, el almacenamiento y los modos de consulta. RAG-Anything suma los parsers, los procesadores por tipo de contenido y las relaciones entre texto, imágenes, tablas y ecuaciones dentro del grafo.

Los dos proyectos están muy conectados:

Si ya tienes una base de conocimiento en LightRAG, puedes pasar esa instancia a RAG-Anything. Hereda el directorio de trabajo, la función del LLM y la de embeddings, y puedes agregar documentos multimodales al mismo almacenamiento.
Desde junio de 2026, el propio LightRAG habilita RAG multimodal mediante una integración nativa de RAG-Anything.

Regla práctica: si tus documentos son casi todo prosa, con LightRAG te alcanza. Si las respuestas están en figuras, tablas o fórmulas, necesitas la capa de RAG-Anything.

¿RAG-Anything o MarkItDown?

Depende de si necesitas un sistema de RAG completo o solo convertir documentos para dárselos a un modelo. MarkItDown es una utilidad ligera de Microsoft que convierte PDFs, Office, imágenes, audio, HTML y EPUB a Markdown, conservando títulos, listas, tablas y enlaces. Está pensada para alimentar LLMs, pero solo convierte: no indexa ni recupera nada.

	MarkItDown	RAG-Anything
Qué produce	Un archivo Markdown	Un grafo de conocimiento consultable
Imágenes	EXIF y OCR; descripciones con LLM opcionales para PPTX e imágenes	Descripción con modelo de visión de cada imagen, vinculada al texto
Búsqueda y respuestas	No incluye	Recuperación híbrida vectorial y de grafo
Modelos necesarios	Ninguno para la conversión básica	LLM, modelo de visión y embeddings
Instalación	`pip install 'markitdown[all]'`	`pip install raganything`

Si vas a pegar un documento en el contexto de Claude Code o de tu agente, MarkItDown es la herramienta más directa. Si tienes una carpeta con cientos de documentos y quieres hacerles preguntas cuyas respuestas están en gráficos y tablas, RAG-Anything es la opción.

¿Cómo se instala RAG-Anything?

Se instala desde PyPI y requiere Python 3.9 o superior:

pip install raganything

# Extras opcionales para más formatos
pip install 'raganything[all]'
pip install 'raganything[image]'   # BMP, TIFF, GIF, WebP
pip install 'raganything[text]'    # TXT, MD

Si prefieres trabajar desde el código fuente, el proyecto usa uv:

git clone https://github.com/HKUDS/RAG-Anything.git
cd RAG-Anything
uv sync
uv sync --all-extras   # todas las funciones opcionales

Hay dos cosas que pip no instala por ti:

LibreOffice es obligatorio para procesar documentos de Office. En macOS es brew install --cask libreoffice, en Ubuntu/Debian sudo apt-get install libreoffice, y en Windows, el instalador del sitio oficial.
Los modelos de MinerU se descargan automáticamente la primera vez que procesas un documento.

Para comprobar que el parser está listo:

mineru --version

¿MinerU, Docling o PaddleOCR: qué parser conviene usar?

Empieza con MinerU, que es el parser por defecto, salvo que tu corpus sea casi todo Office: en ese caso prueba Docling. RAG-Anything soporta tres parsers y eliges uno con el argumento parser o la variable de entorno PARSER:

Parser	Ideal para
MinerU (por defecto)	PDFs, imágenes y Office; OCR y extracción de tablas sólidos; aceleración por GPU
Docling	Documentos de Office y HTML; conserva mejor la estructura del documento
PaddleOCR	Trabajo intensivo de OCR sobre PDFs escaneados e imágenes; convierte Office/TXT/MD a PDF primero

PaddleOCR necesita su propio extra (pip install 'raganything[paddleocr]') y además una versión de paddlepaddle para tu plataforma, que se instala siguiendo su guía oficial.

El método de parsing puede ser auto, ocr o txt. MinerU también acepta opciones como device (cpu, cuda, mps), un rango de páginas y lang para el OCR.

¿Cómo chatear con tus PDFs usando RAG-Anything?

Configuras tres funciones de modelo (un LLM, un modelo de visión y una función de embeddings), procesas el archivo y lo consultas. Las llamadas principales son estas:

config = RAGAnythingConfig(
    working_dir="./rag_storage",
    parser="mineru",
    parse_method="auto",
    enable_image_processing=True,
    enable_table_processing=True,
    enable_equation_processing=True,
)

rag = RAGAnything(
    config=config,
    llm_model_func=llm_model_func,
    vision_model_func=vision_model_func,
    embedding_func=embedding_func,
)

await rag.process_document_complete(
    file_path="path/to/your/document.pdf",
    output_dir="./output",
    parse_method="auto",
)

result = await rag.aquery(
    "What are the main findings shown in the figures and tables?",
    mode="hybrid",
)

Las definiciones completas de las tres funciones de modelo están en el README. El ejemplo oficial las conecta a la API de OpenAI, y el parámetro base_url te permite apuntarlas a cualquier endpoint compatible.

Hay tres formas de consultar:

Consultas de texto, con los modos de LightRAG: hybrid, local, global y naive.
Consultas mejoradas con VLM, que se activan solas cuando hay un modelo de visión configurado. Si el contexto recuperado incluye imágenes, se envían las imágenes mismas al modelo de visión, no solo sus descripciones.
Consultas multimodales (aquery_with_multimodal), que te permiten incluir una tabla o una ecuación en LaTeX dentro de la propia pregunta.

Para procesar una carpeta completa, process_folder_complete recibe una lista de extensiones, un flag recursive y max_workers.

Si ya procesaste tus documentos con otra herramienta, insert_content_list acepta contenido ya parseado y se salta el parsing por completo.

El repositorio incluye un script de punta a punta listo para usar:

python examples/raganything_example.py path/to/document.pdf --api-key YOUR_API_KEY --parser mineru

¿RAG-Anything puede procesar audio y video?

Sí, desde las versiones 1.4.x (septiembre de 2026). Las dos funciones son opcionales.

Audio (.mp3, .wav, .flac, .m4a, .ogg)
- Instala con pip install 'raganything[audio]' y activa enable_audio_processing=True.
- La transcripción se hace en local con faster-whisper, usando el modelo que indiques en WHISPER_MODEL (por defecto, base).
Video (.mp4, .mov, .webm, .avi, .mkv)
- Instala con pip install 'raganything[video]', que además necesita ffmpeg en tu PATH, y activa enable_video_processing=True.
- El pipeline detecta escenas con SceneDetect, describe los fotogramas clave con el modelo de visión, transcribe la pista de audio y lo une todo por marca de tiempo.

Los archivos multimedia entran en la misma base de conocimiento que tus documentos. Así, una sola pregunta puede apoyarse a la vez en la especificación en PDF y en la grabación de una revisión de diseño.

¿RAG-Anything es gratis?

El framework es gratuito y tiene licencia MIT, pero ejecutarlo no necesariamente lo es, porque llama a tres modelos: un LLM, un modelo de visión para las imágenes y un modelo de embeddings. Si usas APIs alojadas, pagas por tokens al indexar, ya que cada imagen y cada tabla pasa por un modelo, y otra vez al consultar.

Algunas partes corren en local sin costo de API:

Los modelos de los parsers (MinerU, Docling, PaddleOCR).
La transcripción de audio con faster-whisper.
Los scripts de prueba de parsing incluidos (office_document_test.py, image_format_test.py, text_format_test.py), que ejercitan el parser sin API key.

Por eso son una buena forma de comprobar qué tan bien se parsean tus documentos antes de gastar en la indexación.

¿Y tú? ¿Qué documentos te gustaría poder consultar con un RAG multimodal en tu trabajo?

Comenta abajo o, si este artículo te llegó por correo, responde directamente al email: tu respuesta se publica aquí.

Relacionado: Building the Entire RAG Ecosystem and Optimizing Every Component

¿Cómo Reducir los Tokens de Razonamiento de Gemma 4? ThinkingCap Explicado

Grego — Sat, 24 Oct 2026 18:43:53 +0000

ThinkingCap es una versión reentrenada de Gemma 4 26B-A4B de Google que usa, en promedio, un 38.9 por ciento menos de tokens de razonamiento con casi la misma precisión: 75.0 frente a 75.2 del modelo base en doce benchmarks. BottleCap AI lo publicó el 23 de octubre de 2026 bajo licencia Apache 2.0, con los pesos completos y versiones GGUF en Hugging Face.

https://huggingface.co/bottlecapai/ThinkingCap-gemma-4-26B-A4B-it

Es un reemplazo directo (drop-in replacement): solo cambian los pesos. La plantilla de chat, el tokenizador y la configuración de muestreo recomendada son los del modelo base. Todas las cifras son mediciones de la propia BottleCap: están bien hechas, pero nadie las ha reproducido de forma independiente todavía. Y, como muestra la ficha GGUF del mismo equipo, el ahorro no llega intacto a los archivos que la mayoría ejecuta en local.

¿Qué son los tokens de razonamiento y por qué conviene reducirlos?

Los tokens de razonamiento (reasoning tokens o thinking tokens, en inglés) son el texto que un modelo se escribe a sí mismo antes de responder: el borrador donde resuelve el problema paso a paso. Casi nunca lo lees, pero lo pagas entero en tiempo, en energía y en ventana de contexto.

En problemas de matemáticas difíciles, Gemma 4 26B escribe entre 15,000 y 22,000 tokens de razonamiento por pregunta. Recortar un tercio de eso cambia cuánto esperas cada respuesta y cuántas peticiones puede atender una sola máquina. La propuesta de BottleCap es exactamente esa: las mismas respuestas, con menos pensamiento por el camino.

¿Qué es Gemma 4 26B-A4B?

gemma-4-26B-A4B-it es el modelo intermedio de la familia Gemma 4 de Google DeepMind, con arquitectura de mezcla de expertos (mixture of experts, MoE). Almacena unos 26,000 millones de parámetros, pero activa solo alrededor de 4,000 millones por token: en cada paso se ejecutan 8 de sus 128 expertos. Eso le da el conocimiento de un modelo grande con un costo de cómputo cercano al de uno pequeño. También acepta imágenes como entrada.

Su modo de razonamiento está apagado por defecto: cada petición tiene que activarlo con enable_thinking. Todas las cifras de ThinkingCap se midieron con el razonamiento activado, así que si ejecutas el modelo sin él, no hay nada que ahorrar.

¿Cuántos tokens de razonamiento ahorra ThinkingCap?

En promedio, un 38.9 por ciento en doce benchmarks. Pero el ahorro varía mucho según la tarea:

Benchmark	Precisión base	Precisión ThinkingCap	Tokens base	Tokens ThinkingCap	Reducción
LongBench v2	59.43	60.88	9,486	2,934	69.1%
AA-LCR	64.62	60.62	6,519	2,655	59.3%
MMLU-Pro	84.55	84.64	3,907	1,989	49.1%
GPQA-Diamond	79.92	78.96	7,699	4,284	44.4%
AIME 2026	86.20	86.72	14,766	8,963	39.3%
HMMT (feb. 2026)	72.92	74.20	22,005	14,717	33.1%
LiveCodeBench v6	76.98	76.96	11,560	8,375	27.6%
τ²-bench	64.25	63.73	4,374	3,466	20.8%
IFBench	76.83	78.67	6,470	5,585	13.7%
Promedio (12 benchmarks)	75.2	75.0	8,773	5,398	38.9%

Selección de filas; la tabla completa de doce benchmarks está en la ficha del modelo.

Las tareas de contexto largo y de conocimiento son las que más recortan; el código recorta menos. El seguimiento de instrucciones y el uso de herramientas en modo agente apenas cambian. La explicación de BottleCap es que esas tareas no consisten en pensar mucho, sino en cumplir una lista de restricciones o una política fija.

La segunda mejora es menos evidente y quizá más útil en la práctica: menos bucles. El modelo base se queda repitiendo el mismo razonamiento en el 3.64 por ciento de sus respuestas; ThinkingCap, en el 0.76 por ciento. En el conjunto de matemáticas más difícil (HMMT de febrero de 2026), los bucles bajan del 17.0 al 4.5 por ciento. Una respuesta en bucle es una respuesta perdida: corre hasta el límite de tokens y no devuelve nada.

¿ThinkingCap pierde precisión frente a Gemma 4?

En promedio, casi nada: 0.15 puntos. Cinco de los doce benchmarks incluso salen ligeramente por delante. Pero "sin pérdida de calidad" es un promedio, no una garantía. Cuatro benchmarks se mueven más de lo que explica el ruido entre ejecuciones:

AA-LCR (razonamiento sobre contexto largo): −4.00 puntos. BottleCap lo reconoce como el único costo real del conjunto. Si tu trabajo consiste en razonar sobre documentos muy largos, pruébalo antes de cambiar.
GPQA-Diamond: −0.96 puntos, y MMMLU (multilingüe): −0.66 puntos.
IFBench (seguimiento de instrucciones): +1.83 puntos, esta vez a favor de ThinkingCap.

En cuanto al método, la evaluación es más sólida que la mayoría de las cifras autodeclaradas:

Ambos modelos medidos por ellos mismos. BottleCap ejecutó el modelo base en lugar de citar las cifras de Google, con el mismo arnés de evaluación, el mismo hardware y la misma configuración de muestreo para los dos.
Muchas semillas por benchmark. Cada uno se ejecutó entre 4 y 64 veces, con intervalos de confianza del 95 por ciento.
El entorno de servicio: vLLM 0.26.0 sobre una NVIDIA GB300 por servidor, con los pesos completos en bf16.

Ese último detalle importa si piensas ejecutarlo en tu propia máquina.

¿Se mantiene el ahorro con la cuantización GGUF en llama.cpp?

Solo en parte, según los propios números de BottleCap. El equipo probó su archivo GGUF recomendado (MXFP4_MOE, 16.6 GB) en llama.cpp frente al ThinkingCap en bf16, en nueve de los doce benchmarks. Con la cuantización, la longitud del razonamiento se desplaza en ambas direcciones:

AIME 2026: 15.5 por ciento más tokens de razonamiento que la versión bf16
IFBench: 6.9 por ciento más
GPQA-Diamond: prácticamente igual
MMLU-Pro: 8.0 por ciento menos
HMMT (feb. 2026): 25.0 por ciento menos

La ficha añade que incluso el GGUF sin cuantizar (BF16) en llama.cpp piensa más que el checkpoint original servido con vLLM: un 6.1 por ciento más en AIME y un 14.7 por ciento más en GPQA. Es decir, el propio runtime cambia la longitud del razonamiento, al margen de la cuantización.

Lo que no se ha publicado es la comparación que de verdad le importa a quien trabaja en local: Gemma 4 base en GGUF frente a ThinkingCap en GGUF, en la misma máquina. Al momento de publicar esta nota (24 de octubre de 2026), ni BottleCap ni nadie más había publicado esa medición. Espera un ahorro real en local, pero no cuentes con el 38.9 por ciento completo.

¿Cómo usar ThinkingCap con llama.cpp u Ollama?

BottleCap documenta llama.cpp. Estos comandos vienen de su ficha GGUF:

# serve an OpenAI-compatible endpoint, thinking on, with the base model's recommended sampling
llama-server -hf bottlecapai/ThinkingCap-gemma-4-26B-A4B-it-GGUF:MXFP4_MOE \
  --jinja --chat-template-kwargs '{"enable_thinking":true}' --reasoning-format deepseek \
  --temp 1.0 --top-p 0.95 --top-k 64 -ub 2048 -b 2048

Con --reasoning-format deepseek, el servidor devuelve el razonamiento en reasoning_content y la respuesta en content, así que puedes contar los tokens de razonamiento tú mismo. BottleCap hace dos advertencias:

Mantén la temperatura en 1.0. La decodificación greedy puede hacer que el modelo entre en bucle.
Mantén -ub 2048 -b 2048 si envías imágenes. Con el tamaño de lote por defecto de llama.cpp, una imagen grande puede tumbar el servidor.

Ollama, LM Studio y Jan cargan los mismos archivos GGUF. La página de Hugging Face genera este comando para Ollama:

ollama run hf.co/bottlecapai/ThinkingCap-gemma-4-26B-A4B-it-GGUF:Q4_K_M

Ten en cuenta dos cosas. Ese comando descarga Q4_K_M, que según BottleCap rindió peor en matemáticas que MXFP4_MOE. Y la ficha de BottleCap no explica cómo activar el razonamiento en Ollama, LM Studio o Jan; sin razonamiento activado, ThinkingCap no tiene nada que ahorrar. Si quieres medir la diferencia, usa llama.cpp.

¿Qué archivo GGUF descargar?

Archivo	Tamaño	Notas
`MXFP4_MOE`	16.6 GB	Recomendado por BottleCap; es el que evaluaron
`Q4_K_M`	17.0 GB	Rindió peor en sus benchmarks de matemáticas que MXFP4_MOE
`IQ4_XS`	13.6 GB	El más pequeño; sin evaluar por BottleCap
`Q6_K` / `Q8_0`	23.3 / 26.9 GB	Más precisión, más memoria
`mmproj-…-f16`	1.19 GB	Proyector de visión, necesario para enviar imágenes

En equipos con poca memoria, IQ4_XS es el que cabe, pero también es el único sin cifras publicadas. Si ya ejecutas Gemma 4 en local, nuestra guía sobre qué variante de Gemma 4 elegir según la RAM de tu Mac cubre la parte de memoria.

Para servidores con GPU, la ficha principal documenta vLLM, con parsers de razonamiento y de llamadas a herramientas:

vllm serve bottlecapai/ThinkingCap-gemma-4-26B-A4B-it --max-model-len 262144 \
  --reasoning-parser gemma4 --enable-auto-tool-choice --tool-call-parser gemma4

Los pesos completos en bf16 ocupan unos 52 GB.

¿Quién está detrás de ThinkingCap?

BottleCap AI. Es el quinto modelo de su serie ThinkingCap, después de dos variantes de Qwen3 27B, Nemotron 3.5 Lightning de NVIDIA y Qwen3.8-Flash-Next, y el primero construido sobre un modelo de Google. Entre los autores que figuran en la cita del modelo está Tomas Mikolov, conocido por word2vec.

BottleCap también vende una versión comercial "PRO" que, según la empresa, recorta el razonamiento un 62 por ciento en promedio. No hay nada público sobre ella, así que tómalo como un argumento de venta. Al momento de publicar esta nota, la página del modelo gratuito en Hugging Face todavía no mostraba cifras de descargas: es muy reciente.

¿Cuándo conviene usar ThinkingCap?

Conviene: trabajo con contexto largo, matemáticas y preguntas de conocimiento donde Gemma 4 piensa mucho, y cualquier entorno donde los bucles te hacen perder tiempo o GPU.
Da igual: seguimiento de instrucciones y uso de herramientas en modo agente, donde el ahorro es pequeño (entre 14 y 21 por ciento).
Pruébalo antes: razonamiento sobre documentos largos (la caída en AA-LCR) y cualquier configuración GGUF en local, donde la cifra principal no se ha medido.

Como es un reemplazo directo con la misma licencia, la forma más barata de salir de dudas es pasar tus propios prompts por los dos modelos con el razonamiento activado y comparar la longitud de reasoning_content.

¿Y tú? ¿Activas el modo de razonamiento cuando ejecutas modelos en local, o lo dejas apagado para ganar velocidad?

Comenta abajo o, si este artículo te llegó por correo, responde directamente al email: tu respuesta se publica aquí.

Relacionado: LM Studio, Ollama o llama.cpp: qué corre de verdad en tu máquina

agent-usage-guard: cómo evitar que Claude Code agote tu límite de uso con subagentes

Grego — Sat, 24 Oct 2026 18:40:12 +0000

agent-usage-guard es un mod de Claude Code, con licencia MIT, que frena el fan-out de subagentes, los prompts con contexto pesado y los reintentos en bucle antes de que agoten tu límite de uso. Lee los porcentajes de la ventana de 5 horas y de la semanal que reporta Claude Code, y cuenta los agentes de todas las sesiones abiertas en tu máquina. Cuando se cruza un umbral, primero te pregunta; si nadie puede responder, se niega. La versión 1.1.0, publicada el 23 de octubre de 2026, agrega un modo de cierre: cuando una ventana del plan llega al 95 por ciento, cada sesión recibe la instrucción de terminar el paso en curso e informar qué queda pendiente.

https://github.com/rbartoli/agent-usage-guard

Actualización, 24 de octubre de 2026: al momento de publicar esta nota, el CHANGELOG del repositorio lista dos correcciones de seguridad todavía sin publicar (Unreleased). Las explicamos en la sección de seguridad.

¿Por qué Claude Code agota el límite de uso tan rápido?

Porque los costos se multiplican, no se suman. El autor identifica cuatro factores que se potencian entre sí: un contexto grande, bucles rápidos de herramientas, agentes en paralelo y reintentos a ciegas.

En el README cuenta la tarde que lo llevó a construir el guard. Le dio a Claude Code un prompt de investigación con esfuerzo máximo, y Claude Code lanzó 394 llamadas a subagentes, 341 de ellas al mismo tiempo. En diez minutos pasó 84 millones de tokens de contexto por la API y la sesión terminó con el mensaje Claude usage limit reached.

Son cifras del propio autor, tomadas de sus registros y no verificadas de forma independiente. Según el mismo relato, en sesenta días de registros tuvo 12 bloqueos. También enlaza reportes públicos parecidos: 339 subagentes a partir de un solo prompt, y la mitad de un plan Max semanal consumida por subagentes que lanzaban otros subagentes.

Cada regla del guard elimina uno de esos cuatro factores.

¿Qué es un mod de Claude Code?

Un mod es un tipo de plugin de Claude Code formado por manejadores de eventos en JavaScript o TypeScript que se ejecutan dentro de Claude Code. Esa es la diferencia con los hooks clásicos que se configuran en settings.json, que ejecutan un script externo. Como un mod vive en el mismo proceso, puede intervenir en un evento antes de que ocurra: retener una llamada a una herramienta mientras te hace una pregunta, reescribir un prompt o rechazar una acción.

Eso es justo lo que agent-usage-guard necesita. Su CHANGELOG explica que la versión anterior (0.2.5) estaba construida sobre hooks de configuración y solo podía aproximar lo que los mods exponen directamente: el contexto en vivo, los porcentajes de la ventana del plan y un evento que se puede rechazar antes de que arranque cada agente.

Los mods están activos por defecto desde Claude Code v2.1.287 en la terminal.

¿Cómo limita los subagentes de Claude Code y el contexto?

El guard actúa en tres momentos: antes de que arranque un agente, antes de que se envíe un prompt y antes de que se ejecute una llamada a una herramienta. Estos son sus valores por defecto según el README:

Área	Regla	Por defecto	Qué hace
Ventana del plan	Ventana así de llena	80%	pregunta antes de nuevos agentes
Ventana del plan	Ventana así de llena	95%	rechaza nuevos agentes
Ventana del plan	La ventana de 5 horas sube así de rápido	20 puntos / 10 min	pregunta
Agentes	Agentes corriendo a la vez, en todas las sesiones de la máquina	4	pregunta
Agentes	Agentes iniciados o reanudados cada 10 minutos	12	pregunta
Agentes	Tokens procesados por subagentes cada 10 minutos	10M	pregunta
Agentes	Subagentes que lanzan sus propios agentes	profundidad 1	rechaza
Contexto	Aviso único para que Claude acote el turno	300k tokens	agrega una nota
Contexto	Prompt que volvería a leer este contexto	500k tokens	pregunta: compactar y enviar, enviar igual o cancelar
Contexto	Llamadas a herramientas cada 10 min con este contexto	20 llamadas a 400k	pregunta
Contexto	Sesión pesada inactiva el tiempo suficiente para que expire su caché	150k tokens, 1 h inactiva	pregunta antes de reescribir la caché
Bucles	La misma llamada falla una y otra vez	3 fallos idénticos	rechaza el reintento idéntico
Bucles	Agentes rechazados en 10 minutos	5	pausa los lanzamientos 10 min

La regla de la sesión inactiva tiene que ver con la caché de prompts, que explicamos en detalle en Tu caché de 5 minutos no dura 5 minutos. Si todavía no usas subagentes, empieza por Sub-agents en Claude Code.

Dos decisiones de diseño importan en el uso diario:

Una respuesta vale por un rato. Si permites algo, el guard no vuelve a preguntar hasta que la condición desaparece. Una ventana del plan queda permitida hasta que se reinicia, y los conteos de agentes quedan permitidos durante 10 minutos. El autor lo incorporó porque su versión anterior preguntó 136 veces en sesiones de contexto alto y la respuesta fue "sí" en 132.
Sin una persona, rechaza. En claude -p, el Agent SDK o el modo dontAsk, rechaza y explica el motivo. Claude lee el rechazo como el resultado de la herramienta, así que puede esperar, agrupar el trabajo o detenerse. Los rechazos repetidos suben de tono, y el tercero le pide a Claude que termine el turno.

¿Qué hace el nuevo modo de cierre al 95 por ciento?

Según el CHANGELOG de la 1.1.0, cuando cualquier ventana del plan en la máquina llega al 95 por ciento, el siguiente prompt de cada sesión lleva una nota para Claude: termina el paso en curso, no empieces nada grande y cierra el turno con lo hecho y lo pendiente.

El autor explica por qué lo agregó. Los bloqueos que seguía viendo después de la 1.0 venían de muchas sesiones principales corriendo en paralelo, y eso no lo frenaba ninguna regla. Ahora, cuando llega el bloqueo, las encuentra en un punto limpio y no a mitad de un cambio. Una sesión inactiva también se entera de que otra sesión llenó la ventana. Cada sesión recibe el aviso una sola vez, y solo vuelve a recibirlo cuando la ventana baja del umbral, por ejemplo después de su reinicio.

La versión 1.1.1, publicada el mismo día, corrige un doble conteo: desde Claude Code 2.1.299, reanudar un subagente con SendMessage contaba como dos inicios. También hace que /agent-guard status muestre qué versión está corriendo.

¿Cómo se instala agent-usage-guard en Claude Code?

Dentro de Claude Code v2.1.287 o posterior, ejecuta:

/plugin marketplace add rbartoli/agent-usage-guard
/plugin install agent-usage-guard@agent-usage-guard
/reload-plugins

Después ejecuta /agent-guard para ver lo que ve el guard.

Estos son los comandos que vas a usar:

/agent-guard [status]                          what the guard sees right now
/agent-guard allow [agents|context] [minutes]  lift its limits for this session (default: all, 10 min)
/agent-guard pause [minutes]                   the same as allow, for every limit
/agent-guard resume                            end an allow early
/agent-guard report [days]                     what it did on this machine (default: 7 days)

/agent-guard se ejecuta sin iniciar un turno del modelo, así que Claude nunca ve una anulación y no puede tomarla como permiso.

¿Cómo se ajustan los umbrales?

Con variables de entorno, o dentro de env en ~/.claude/settings.json. Algunas de las más útiles:

AGENT_GUARD_AGENT_MAX: agentes corriendo a la vez en la máquina (por defecto 4).
AGENT_GUARD_LIMIT_ASK_PERCENT y AGENT_GUARD_LIMIT_DENY_PERCENT: umbrales para preguntar y para rechazar (80 y 95).
AGENT_GUARD_CONTEXT_HARD: contexto a partir del cual un prompt pregunta antes de enviarse (500000).
AGENT_GUARD=0: apaga el guard sin desinstalarlo.

El README documenta 22 variables en total.

¿Funciona con una API key?

Sí, con dos diferencias. Las sesiones con API key no reportan los porcentajes de la ventana del plan, así que solo se aplican los presupuestos de tokens y de conteo de agentes. Además, la caché de prompts dura cinco minutos en lugar de una hora, por lo que el README recomienda AGENT_GUARD_DORMANT_SECONDS=300. Lo mismo vale si usas uso adicional (extra usage).

¿Qué no puede ver?

El README es explícito sobre sus puntos ciegos, verificados contra Claude Code v2.1.295:

No cuenta sesiones en otras máquinas, porque los registros compartidos viven en el almacén de mods de cada equipo.
No ve a los compañeros de equipo (teammates) que corren en su propio panel de terminal, porque corren en otros procesos.
Los forks de /subtask, y todo lo que arranca sin el evento agent.spawn, se cuentan pero nunca se retienen.
No corre en una sesión WSL de la app de escritorio.

Los límites nativos de Claude Code siguen vigentes: una sesión admite hasta 20 subagentes concurrentes y tres niveles de anidamiento, pero no hay límite al total de agentes que una sesión lanza. Los valores por defecto del guard son más estrictos y abarcan todas las sesiones.

¿Es seguro instalar un mod de Claude Code?

Un mod corre con tus permisos y no está aislado en un sandbox. La documentación de Anthropic lo dice sin rodeos: un mod puede leer tus archivos, tus variables de entorno y tu sesión. Según las notas de privacidad del autor, el guard son unas 2.400 líneas de TypeScript sin dependencias, no hace peticiones de red ni inicia procesos, y guarda conteos y rangos aproximados, nunca el texto de los prompts ni las entradas de las herramientas. Puedes revisar qué APIs usa con claude plugin validate . antes de instalarlo.

Al momento de publicar esta nota, el CHANGELOG lista dos correcciones de una revisión de seguridad del 24 de octubre de 2026 que todavía no forman parte de una versión publicada:

Hasta que salga esa corrección, cualquier otro plugin instalado podía ejecutar /agent-guard allow y levantar todos los límites hasta por ocho horas.
Una pregunta que terminaba sin respuesta podía dejar arrancar un agente; con la corrección cuenta como "no".

Antes de confiar en el guard en sesiones con otros mods instalados, comprueba que tu versión incluya ambas correcciones. Para revisar si cualquier mod es seguro, mira cómo probamos ModVet, el escáner que revisa un plugin antes de instalarlo.

¿agent-usage-guard o Claude HUD?

Resuelven problemas distintos y funcionan bien juntos. Claude HUD te muestra qué está haciendo Claude Code y cuánto te cuesta. agent-usage-guard le pone un techo a ese costo y lo aplica antes de que se gaste.

¿Y tú? ¿Cuántos subagentes dejas correr en paralelo en Claude Code antes de empezar a preocuparte por el límite?

Comenta abajo o, si este artículo te llegó por correo, responde directamente al email: tu respuesta se publica aquí.

Relacionado: Claude HUD: El Plugin que te Dice Exactamente Qué Está Haciendo Claude Code (y Cuánto te Está Costando)

SvelteKit 3: cómo migrar con sv migrate y el cambio de $lib que el comando no hace por ti

Grego — Fri, 02 Oct 2026 16:10:23 +0000

SvelteKit 3.0 salió el 1 de octubre de 2026 y casi toda la migración se automatiza con un comando, npx sv migrate sveltekit-3. Lo que ese comando no hace es cambiar $lib por #lib: ese paso es manual. En esta guía verás qué cambia, qué resuelve la herramienta de migración y qué te toca hacer a ti.

El equipo de Svelte lo presenta como el mismo framework con más pulido y más seguridad de tipos. Para la API del día a día es cierto, pero la estructura del proyecto cambia: la configuración se muda de archivo, el alias de importación más usado se reemplaza, los módulos de variables de entorno quedan obsoletos y los service workers se configuran de otra manera.

¿Qué es SvelteKit y en qué se diferencia de Svelte?

SvelteKit es el framework oficial de aplicaciones para Svelte: se encarga del enrutamiento, la carga de datos, el renderizado en servidor y el despliegue mediante adapters. Es a Svelte lo que Next.js es a React. Svelte compila los componentes y SvelteKit los convierte en una aplicación desplegable, ya sea con renderizado en servidor, prerenderizada como sitio estático o como single-page app. Tiene licencia MIT y se desarrolla en github.com/sveltejs/kit.

¿Qué cambia en SvelteKit 3?

El anuncio oficial destaca cinco cambios, y cuatro de ellos afectan a archivos que ya tienes en tu proyecto.

La configuración pasa de `svelte.config.js` a `vite.config`

svelte.config.js ya no está soportado. La configuración ahora se pasa directamente al plugin sveltekit de Vite, y las opciones que antes vivían en config.kit.* pasan a ser opciones de primer nivel del plugin:

import adapter from '@sveltejs/adapter-auto';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
    plugins: [
        sveltekit({
            adapter: adapter()
        })
    ]
});

Las opciones que no son de SvelteKit se reenvían a vite-plugin-svelte. Con la mudanza desaparecen varias opciones:

files.lib
vitePlugin
preloadStrategy
prerender.origin, reemplazada por la nueva paths.origin
csrf.checkOrigin, reemplazada por csrf.trustedOrigins

`$lib` pasa a ser `#lib`

SvelteKit ya no genera el alias $lib. En su lugar declaras tú mismo #lib usando los subpath imports de Node.js, que Vite y TypeScript resuelven de forma nativa. Es el cambio que sv migrate no hace por ti; los pasos están más abajo.

Las variables de entorno pasan a `$app/env`

Los módulos $env/... quedan obsoletos en favor de $app/env/private y $app/env/public. $app/environment se renombra a $app/env, y ahora también puedes importarlo dentro de un service worker.

Los service workers necesitan menos código repetitivo

El módulo $service-worker se eliminó y sus exportaciones se reparten entre módulos estándar:

version viene de $app/env.
assets, immutable y prerendered vienen del nuevo $app/manifest.
Las utilidades de rutas vienen de $app/paths.

Un nuevo módulo, $app/service-worker, te da un contexto de service worker con tipos. Además, SvelteKit ahora registra el service worker como módulo ES y no como script clásico.

El quinto cambio destacado es el manejo de errores. En SvelteKit 3, handleError recibe todos los errores, incluidos los esperados que creas con error(...), y los errores de renderizado se envían al +error.svelte más cercano.

¿Qué necesitas antes de migrar a SvelteKit 3?

Según la guía oficial de migración, SvelteKit 3 exige estas versiones mínimas:

Dependencia	Mínimo
Node	22.17
TypeScript	6
Svelte	5.57.1
Vite	8.0.12
`@sveltejs/vite-plugin-svelte`	7

El equipo de Svelte recomienda actualizar primero a la última versión 2.x, porque esa versión muestra avisos de obsolescencia dirigidos exactamente al código que tendrás que cambiar. Haz commit de tu proyecto antes de empezar: si el árbol de trabajo tiene cambios sin confirmar, sv migrate te lo avisará.

¿Cómo migrar a SvelteKit 3 con `sv migrate`?

El anuncio de lanzamiento propone un comando que lo hace todo de una vez:

npx sv migrate sveltekit-3 --tasks all --confirm

La documentación del CLI recomienda un enfoque más prudente: ejecuta una tarea por vez y haz commit después de cada una, para que cada diff sea fácil de revisar. Para ver las tareas disponibles sin ejecutar nada, usa:

npx sv migrate sveltekit-3 --tasks

La migración sveltekit-3 se compone de nueve tareas. Las dos primeras son requisitos previos y se ejecutan siempre:

Tarea	Qué hace
`package-json`	Actualiza las versiones de los paquetes para SvelteKit 3
`tsconfig`	Hace que tu `tsconfig.json` extienda `$app/tsconfig` en lugar de `.svelte-kit/tsconfig.json`
`svelte-config`	Mueve las opciones soportadas de `svelte.config.` a `vite.config.`
`environment`	Reemplaza los módulos de entorno antiguos por `$app/env` y crea las declaraciones `src/env.js` o `src/env.ts` cuando hacen falta
`paths`	Migra las APIs obsoletas de `$app/paths` (`base`, `assets` y `resolveRoute` se reemplazan por `asset()` y `resolve()`)
`external-redirects`	Adapta las redirecciones externas al nuevo comportamiento
`shallow-routing`	Reemplaza `pushState` y `replaceState` por `goto(..., { shallow: true })`
`params`	Reúne los param matchers en un único `src/params.js` o `src/params.ts`
`app-state`	Migra `$app/stores` a `$app/state`

Para ejecutar una sola tarea:

npx sv migrate sveltekit-3 --tasks svelte-config

La documentación advierte que el proyecto no tiene por qué funcionar si solo se ejecutaron algunas tareas: la mayoría de las aplicaciones necesitan todas las que les correspondan. La herramienta solo reescribe los patrones que puede identificar con seguridad. Donde no puede, deja un comentario @migration-task, así que busca ese marcador exacto en el proyecto antes de dar la migración por terminada.

¿Cómo arreglar `$lib` después de migrar a SvelteKit 3?

$lib no aparece en la lista de tareas. Cuando sv migrate termina, cada importación con $lib en tu código sigue apuntando a un alias que SvelteKit 3 ya no genera. Para arreglarlo hacen falta tres pasos.

1. Declara #lib en package.json:

{
    "imports": {
        "#lib": "./src/lib/index.js",
        "#lib/*": "./src/lib/*"
    }
}

2. Reemplaza $lib por #lib en todo el código.

3. Añade la extensión de archivo a esas importaciones. Los subpath imports la exigen, así que el cambio no es un simple buscar y reemplazar del prefijo:

// antes
import { foo } from '$lib/foo';
// después
import { foo } from '#lib/foo.js';

La opción files.lib también desapareció: si habías personalizado tu directorio lib, apunta las entradas de imports a ese directorio.

¿Qué más puede romperse en producción?

Estos cambios de la guía de migración modifican el comportamiento en tiempo de ejecución, y algunos no producen ningún error de build:

$app/stores se eliminó, no solo quedó obsoleto. La tarea app-state migra los archivos .svelte, así que revisa si quedan usos en otros archivos.
adapter-node elimina la variable de entorno ORIGIN. Define paths.origin en tu configuración de Vite.
adapter-vercel ya no soporta el runtime edge.
Las APIs de Cloudflare salen de platform. Importa env desde cloudflare:workers; cf ahora es una propiedad de request.
Las redirecciones externas necesitan permiso explícito. Pasa { external: true } o una lista de orígenes permitidos a redirect(...).
Los nombres de cookies deben ser ASCII. SvelteKit ahora usa cookie v2, que rechaza caracteres no ASCII como á en los nombres de las cookies. Conviene revisarlo en aplicaciones en español.
Las cookies usan path: '/' por defecto, en lugar de la ruta de la petición actual.
error(...) recibe un string como segundo argumento. Las propiedades adicionales ahora van en un tercer argumento.
goto() rechaza las URLs que no corresponden a una ruta de tu aplicación. Para navegar a un sitio externo, usa window.location.href.
Las respuestas 2xx vacías se devuelven sin cuerpo, como exige la especificación HTTP.

¿Están listas las remote functions en SvelteKit 3?

Todavía no. Al momento de publicar esta nota, las remote functions seguían siendo experimentales: requieren el flag experimental.remoteFunctions junto con la opción asíncrona del compilador de Svelte. El equipo de Svelte las señala como su máxima prioridad. Si las estabas esperando, igual vale la pena actualizar ya, porque la migración no depende de ellas.

Si estás siguiendo otras actualizaciones mayores de esta temporada, ya contamos qué cambia en htmx 4.0 si vienes de htmx 2.

https://svelte.dev/blog/sveltekit-3-is-here