repowise: inteligencia de código para agentes de IA con 27× menos tokens

⏱️ Lectura: 13 min

Cuando un agente de IA como Claude Code se enfrenta a un repositorio real, tiene un problema que nadie enuncia en voz alta: ve el código, pero no ve nada más. No sabe quién escribió cada archivo, qué ficheros suelen cambiar juntos aunque no se importen entre sí, cuáles llevan meses sin tocarse, cuáles están muertos, ni por qué se tomaron las decisiones arquitectónicas que tomaron. Tiene la fuente y cero conocimiento institucional. Eso lo obliga a grep todo, leer decenas de archivos y reconstruir desde cero contexto que los humanos del equipo ya tienen interiorizado.

📑 En este artículo

1. Introducción: qué enseña este material
2. A quién está dirigido
3. Estructura del material
4. Secciones más valiosas
   1. 1. «What repowise builds» — las cuatro capas de inteligencia
   2. 2. «Seven MCP tools» — diseño de herramientas orientado a tareas
   3. 3. «Workspaces» — inteligencia multi-repo
   4. 4. El benchmark y la sección «Token efficiency»
5. Ruta de lectura recomendada
   1. Ruta 1: «Solo quiero probarlo en mi repo» (30 minutos)
   2. Ruta 2: «Quiero entender el diseño antes de adoptarlo» (2 horas)
   3. Ruta 3: «Trabajo en un monorepo o multi-repo»
   4. Ruta 4: «Estoy construyendo mi propio servidor MCP»
6. Limitaciones y qué queda fuera
7. Conclusión
8. Referencias
   1. 📚 Artículos relacionados

repowise es un proyecto open source que ataca exactamente ese problema. Indexa el codebase en cuatro capas de inteligencia y las expone a cualquier agente compatible con el Model Context Protocol (MCP) a través de siete herramientas específicas. En esta reseña repasamos qué es, cómo está estructurada su documentación, a quién le resulta útil y por dónde empezar a leerla según el objetivo que tengas.

Introducción: qué enseña este material

El repositorio repowise-dev/repowise (1.220 estrellas, 180 forks, escrito en Python) es simultáneamente un paquete instalable con pip install repowise y una pequeña biblioteca de documentación que explica cómo funciona por dentro. El README y los documentos en docs/ enseñan tres cosas en capas concéntricas:

• Qué problema resuelve — por qué un agente de IA necesita algo más que la fuente cruda para ser útil en un repositorio mediano o grande.
• Cómo lo resuelve — cuatro capas de inteligencia (grafo de dependencias, historia de git, wiki autogenerada, registro de decisiones) y siete herramientas MCP diseñadas alrededor de tareas, no de entidades.
• Qué evidencia hay de que funciona — un benchmark abierto (repowise-bench) con números concretos: 27× menos tokens por consulta, 36% más barato, 49% menos llamadas a herramientas, con calidad de respuesta en paridad.

No es un manual de programación: es la documentación de un producto técnico con licencia AGPL v3, más una metodología de medición. Leerlo entero te deja con una idea muy clara de cómo debería verse la integración entre agentes de IA y codebases reales, y por qué casi ninguna integración actual lo hace bien.

A quién está dirigido

El material no es para cualquier desarrollador curioso. Tiene un lector objetivo bastante definido y conviene ser honesto al respecto antes de invertir tiempo.

• Equipos de ingeniería que ya usan Claude Code u otros agentes vía MCP sobre codebases de producción. Si ya viste a tu agente perderse en un monorepo de 3.000 archivos o quemar tokens leyendo cinco veces el mismo utilidad, esta es tu lectura.
• Desarrolladores de herramientas para IA — gente construyendo su propio servidor MCP o integrando agentes con sistemas internos. El diseño de las siete herramientas de repowise es probablemente el aporte más transferible del repo: una lección concreta de cómo no diseñar tools para LLMs.
• Tech leads y arquitectos interesados en capturar decisiones arquitectónicas de forma estructurada (los WHY, DECISION, TRADEOFF inline), y en cómo detectar hotspots, bus factor, co-changes ocultos y código muerto.
• Investigadores de ingeniería de software que quieran un benchmark reproducible para medir el efecto de dar contexto estructurado a un LLM. El proyecto hermano repowise-bench es justamente eso.

No es para: alguien aprendiendo a programar, alguien que nunca haya tocado un agente de IA, o alguien que busque una introducción a MCP desde cero. Para eso último, conviene leer primero el spec de modelcontextprotocol.io y volver aquí después.

Estructura del material

La documentación real del repo se organiza en un README extenso (la puerta de entrada) y una serie de documentos en la carpeta docs/. El README cubre el 80% de los casos de uso; los documentos específicos profundizan en escenarios concretos. Esta es la estructura tal como aparece referenciada:

• README.md — visión general, benchmarks, las cuatro capas, las siete herramientas, quickstart, workspaces, CLI, lenguajes soportados.
• docs/QUICKSTART.md — instalación y primer init.
• docs/USER_GUIDE.md — guía de uso completa, día a día.
• docs/CLI_REFERENCE.md — referencia exhaustiva de todos los comandos de la CLI.
• docs/MCP_TOOLS.md — especificación detallada de las siete herramientas MCP, sus parámetros y cuándo llamarlas.
• docs/WORKSPACES.md — modo multi-repo, co-changes cross-repo, contratos de API y queries federadas.
• docs/AUTO_SYNC.md — métodos de sincronización: hooks de git, file watcher, webhooks de GitHub/GitLab, polling.

El repositorio hermano repowise-dev/repowise-bench complementa la documentación con el benchmark SWE-QA y la metodología de medición. No está dentro del repo principal pero es referencia obligada para evaluar los números.

Secciones más valiosas

De toda esa estructura, hay cuatro bloques que concentran el valor editorial del material. Si tu tiempo es escaso, estos son los que justifican la lectura.

1. «What repowise builds» — las cuatro capas de inteligencia

Esta sección del README es la columna vertebral conceptual. Explica cómo se combinan cuatro fuentes heterogéneas de información para producir algo que un agente puede consumir eficientemente:

• Graph Intelligence — tree-sitter parsea cada archivo en 14 lenguajes hacia un grafo de dos niveles (archivos y símbolos). Un resolver de llamadas de 3 niveles con scoring de confianza maneja aliases, barrel re-exports y namespace imports. Detección de comunidades con Leiden, PageRank, centralidad de intermediación, componentes fuertemente conectados y trazado de flujo desde entry points.
• Git Intelligence — 500 commits de historia convertidos en señales: hotspots (churn × complejidad), porcentaje de ownership por ingeniero, pares de co-change (archivos que cambian juntos sin importarse) y mensajes de commits significativos.
• Documentation Intelligence — un wiki generado por LLM para cada módulo y archivo, reconstruido incrementalmente en cada commit. Tracking de cobertura, scoring de freshness y búsqueda semántica vía RAG.
• Decision Intelligence — la capa que casi nadie tiene. Decisiones arquitectónicas capturadas desde git, desde marcadores inline (WHY, DECISION, TRADEOFF) y desde la CLI, enlazadas a los nodos del grafo que gobiernan y trackeadas por staleness.

Es una excelente lectura incluso si no planeas usar repowise: es un mapa de qué fuentes de contexto son extraíbles de un repositorio y cómo se relacionan entre sí.

2. «Seven MCP tools» — diseño de herramientas orientado a tareas

Quizá la parte más transferible de toda la documentación. La tesis es simple y contundente: la mayoría de herramientas MCP están diseñadas alrededor de entidades (un módulo, un archivo, un símbolo), lo que fuerza a los agentes a encadenar docenas de llamadas secuenciales. repowise las diseña alrededor de tareas: pasás múltiples objetivos en una sola llamada y recibís contexto completo.

Las siete herramientas son: get_overview(), get_answer(question), get_context(targets, include?), search_codebase(query), get_risk(targets?, changed_files?), get_why(query?) y get_dead_code(min_confidence?, include_internals?). El ejemplo canónico del README muestra cómo resolver «agregar rate limiting a todos los endpoints de la API» con 5 llamadas en lugar de ~30:

get_overview()
get_context(["middleware", "api/routes", "payments"])
get_risk(["middleware/auth.ts"])
get_why("rate limiting")
search_codebase("rate limit OR throttle OR retry")

Leer docs/MCP_TOOLS.md después del README consolida la lección: diseñá tools que colapsen ciclos de búsqueda/lectura/razonamiento en un solo round-trip.

3. «Workspaces» — inteligencia multi-repo

La mayoría de codebases reales no son un solo repo. docs/WORKSPACES.md explica cómo repowise indexa varios repositorios juntos y produce señales que un único repo no puede ofrecer:

• Co-changes cross-repo — por ejemplo, backend/api/routes.py y frontend/src/api/client.ts cambiando siempre en la misma ventana temporal.
• Extracción de contratos de API — escanea handlers HTTP (Express, FastAPI, Spring, Go), definiciones gRPC, publishers y subscribers, y matchea providers con consumers entre repos.
• Mapeo de dependencias de paquetes — lee package.json, pyproject.toml, go.mod, pom.xml para detectar cuándo un repo depende de otro como paquete.
• Queries MCP federadas — un único servidor MCP sirve todos los repos; pasás repo="backend" o repo="all" a cualquier tool.

Para equipos con arquitectura de microservicios o monorepos federados, esta sección es el argumento comercial más fuerte del proyecto.

4. El benchmark y la sección «Token efficiency»

La sección de benchmarks del README es, en sí misma, un pequeño ensayo sobre cómo hacer (y cómo no hacer) mediciones justas. Sobre 48 tareas pareadas de pallets/flask usando claude-sonnet-4-6: el costo promedio baja de $0,1396 a $0,0890 por tarea (−36%), el wall time de 41,7s a 33,9s (−19%), las llamadas a herramientas de 7,4 a 3,8 (−49%) y los archivos leídos de 1,9 a 0,2 (−89%). 32 de 48 tareas (67%) resultan más baratas con repowise a calidad equivalente (Δ del juez ≈ −0,01).

La sección de eficiencia de tokens aporta el dato más citado del repo: para entender un commit, la estrategia naive (contenido completo de los archivos modificados) pide 64.039 tokens por commit, git diff solo pide 14.888, y repowise get_context pide 2.391. Eso es 26,8× menos que naive en pooled y 1.214× menos en el mejor caso, con la misma lista de archivos y el mismo tokenizer (cl100k_base).

Ruta de lectura recomendada

Dependiendo de qué quieras conseguir, el orden óptimo de lectura cambia. Estas son cuatro rutas concretas:

Ruta 1: «Solo quiero probarlo en mi repo» (30 minutos)

1. Leer la sección Quickstart del README (5 min).
2. Ejecutar pip install repowise y repowise init en un proyecto personal. El init inicial toma ~25 minutos, así que podés seguir leyendo mientras corre.
3. Mientras indexa, leer docs/QUICKSTART.md.
4. Cuando termine, correr repowise serve y explorar el dashboard local.

Ruta 2: «Quiero entender el diseño antes de adoptarlo» (2 horas)

1. README completo, sin saltar el benchmark.
2. docs/MCP_TOOLS.md — la parte más densa técnicamente.
3. docs/USER_GUIDE.md — cómo se usa en el día a día.
4. Opcional: repowise-bench para validar los números con ojo crítico.

Ruta 3: «Trabajo en un monorepo o multi-repo»

1. Sección Workspaces del README.
2. docs/WORKSPACES.md completo.
3. docs/AUTO_SYNC.md para entender los mecanismos de sincronización (hooks, watchers, webhooks, polling).
4. Comandos repowise workspace de la CLI Reference.

Ruta 4: «Estoy construyendo mi propio servidor MCP»

1. Las secciones What repowise builds y Seven MCP tools del README.
2. docs/MCP_TOOLS.md con atención al parámetro include de get_context — es un patrón reutilizable.
3. El ejemplo de tool call comparison (5 llamadas vs 30) como caso de estudio de diseño.

Limitaciones y qué queda fuera

El material es honesto pero no exhaustivo. Hay varias áreas donde la documentación es ligera o directamente queda fuera del alcance:

• Soporte de lenguajes — el tier «Full» cubre Python, TypeScript, JavaScript, Java, Go, Rust y C++. Si tu stack principal es Ruby, PHP, Elixir, Kotlin, Swift, Scala o C, el análisis será parcial o inexistente. El README no detalla qué funciona en tiers inferiores.
• Costo del init inicial — ~25 minutos para un proyecto de 3.000 archivos es significativo, y el material no explica cómo escala a 50.000 o 100.000 archivos. Tampoco detalla el costo en llamadas a LLM del indexado inicial (aunque existe repowise costs para trackearlo después).
• Privacidad de la wiki generada — el wiki autogenerado por LLM implica enviar código a un modelo. El README no entra en detalle sobre qué modelos se usan por defecto, si hay opción on-prem, ni cómo manejar repositorios con datos sensibles. Para uso corporativo serio, eso es un vacío notable.
• Licencia AGPL v3 — el proyecto es open source pero con copyleft fuerte. Si lo integrás en un producto SaaS, la AGPL te obliga a liberar las modificaciones. Para la mayoría de equipos que solo lo usan como herramienta interna no hay problema; para quien quiera incrustarlo en un producto comercial, sí.
• Benchmark acotado — las 48 tareas sobre pallets/flask son un buen sanity-check, pero flask es un codebase Python mediano, bien estructurado y con historia limpia. La generalización a monorepos sucios, codebases Java legacy o proyectos con poco historial de git no está medida.
• Perspectiva LATAM — el material está en inglés y los ejemplos asumen un stack norteamericano típico. Para equipos en español hay que traducir mentalmente, y no hay consideraciones sobre latencia hacia APIs de LLM desde la región.

Ninguno de estos huecos invalida el proyecto, pero conviene conocerlos antes de adoptarlo en un entorno de producción serio.

Conclusión

repowise es uno de los proyectos open source más interesantes que han aparecido alrededor de MCP en 2026. No porque el Model Context Protocol sea nuevo (no lo es), sino porque repowise demuestra en código y con números qué significa diseñar bien un servidor MCP: cuatro capas de inteligencia complementarias, siete herramientas pensadas alrededor de tareas, un benchmark abierto que mide con rigor, y un orden de magnitud menos de tokens consumidos por consulta.

Para equipos que ya invirtieron en Claude Code o cualquier agente MCP-compatible sobre un codebase real, el material del repo es una lectura útil aunque decidan no adoptar la herramienta: el enfoque de diseño es transferible. Para quien esté construyendo su propio tooling alrededor de IA y desarrollo, las secciones sobre las cuatro capas y las siete herramientas son prácticamente una guía de estilo implícita.

Vale la pena darle una tarde entera de lectura, instalarlo en un proyecto personal y ver qué dice el dashboard local. El repowise status inicial suele ser sorprendente: nadie tiene una idea exacta de cuánto código muerto acumula su repo, ni de dónde están los hotspots reales, hasta que una herramienta se los pone frente a los ojos.

Podés explorar el proyecto directamente en el Repositorio oficial en GitHub y probar la demo en repowise.dev/examples.

Referencias

• repowise-dev/repowise — repositorio oficial en GitHub
• repowise.dev — homepage oficial y demos
• repowise-dev/repowise-bench — benchmark SWE-QA sobre pallets/flask
• modelcontextprotocol.io — especificación del Model Context Protocol
• repowise en PyPI

📱 ¿Te gusta este contenido? Únete a nuestro canal de Telegram @programacion donde publicamos a diario lo más relevante de tecnología, IA y desarrollo. Resúmenes rápidos, contenido fresco todos los días.