codesight

---

0 dependencies · Node.js >= 18 · 149 tests · 14 MCP tools · MIT · tested on 25+ OSS projects across 14 languages

Compatibilidad

Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Windsurf, Cline, Aider y cualquier herramienta que lea markdown.

Instalación

npx codesight

Eso es todo. Ejecútalo en la raíz de cualquier proyecto. Sin configuración, sin preparación, sin claves API.

npx codesight --wiki                       # Generate wiki knowledge base (.codesight/wiki/)
npx codesight --init                       # Generate CLAUDE.md, .cursorrules, codex.md, AGENTS.md
npx codesight --open                       # Open interactive HTML report in browser
npx codesight --mcp                        # Start as MCP server (14 tools) for Claude Code / Cursor
npx codesight --blast src/lib/db.ts        # Show blast radius for a file
npx codesight --profile claude-code        # Generate optimized config for a specific AI tool
npx codesight --benchmark                  # Show detailed token savings breakdown
npx codesight --native-ast                 # Opt-in: AST plugins for more languages (see docs/wasm-plugins.md)
npx codesight --mode knowledge             # Map knowledge base (.md notes → KNOWLEDGE.md)
npx codesight --mode knowledge ~/vault     # Map Obsidian vault, ADRs, meeting notes, retros

Base de Conocimiento Wiki (v1.6.2)

Inspirado en el patrón wiki LLM de Karpathy — pero compilado desde AST, no desde un LLM. Cero llamadas API. 200ms.

npx codesight --wiki

Genera .codesight/wiki/ — una base de conocimiento persistente de tu código que sobrevive en cada sesión:

.codesight/wiki/
  index.md      — catalog of all articles (~200 tokens) — read this at session start
  overview.md   — architecture, subsystems, high-impact files (~500 tokens)
  auth.md       — auth routes, middleware, session flow
  payments.md   — payment routes, webhook handling, billing flow
  database.md   — all models, fields, relations, high-impact DB files
  users.md      — user management routes and related models
  ui.md         — UI components with props
  log.md        — append-only record of every wiki operation

Por qué esto reduce aún más el uso de tokens:

En lugar de cargar el mapa de contexto completo de 5K tokens en cada conversación, tu IA lee un artículo específico:

Pregunta	Sin wiki	Con wiki
"¿Cómo funciona la autenticación?"	~12K tokens (lee 8+ archivos)	~300 tokens (auth.md)
"¿Qué modelos existen?"	~5K tokens (CODESIGHT.md)	~400 tokens (database.md)
Inicio de nueva sesión	~5K tokens (recarga completa)	~200 tokens (index.md)

Persistente entre sesiones. La wiki vive en .codesight/wiki/, confirmada en git. Cada nueva sesión de Claude Code, Cursor o Codex comienza con conocimiento completo del código desde el primer mensaje.

Auto-regeneración. Usa --watch para mantener la wiki actualizada mientras programas. Usa --hook para regenerarla en cada commit.

3 nuevas herramientas MCP para acceso a la wiki:

Herramienta	Qué hace
codesight_get_wiki_index	Obtener el catálogo de la wiki (~200 tokens) al inicio de la sesión
codesight_get_wiki_article	Leer un artículo por nombre: auth, database, payments, etc.
codesight_lint_wiki	Verificación de salud: artículos huérfanos, enlaces cruzados faltantes, contenido desactualizado

La diferencia clave con las herramientas wiki de propósito general: codesight ya conoce tus rutas, esquema, radio de impacto y middleware desde AST — no se necesita LLM para extraer la estructura del código. La wiki es una capa narrativa sobre datos que tu código ya contiene.

Modo Conocimiento (v1.9.3)

No solo código — tus decisiones, notas de reuniones, ADRs y retrospectivas aportan tanto contexto como el propio código. --mode knowledge los mapea de la misma manera que codesight mapea el código.

npx codesight --mode knowledge              # Scan current directory for .md files
npx codesight --mode knowledge ~/vault      # Scan an Obsidian vault
npx codesight --mode knowledge ./docs       # Scan a project docs folder

Genera .codesight/KNOWLEDGE.md — un resumen compacto de contexto para IA:

# Knowledge Map — my-project

> 47 notes · 12 decisions · 8 open questions · 2025-09-01 → 2026-04-01

## Key Decisions (12)

- [2026-03-20] Going with Polar.sh over Stripe Connect — simpler global payments
- [2026-03-15] Decided to use PostgreSQL — better JSON support and Drizzle compatibility
- [2026-02-10] Will use Redis for rate limiting — BullMQ already in stack

## Open Questions (8)

- Should we support PayPal later?
- When do we start the Stripe marketplace application?

## Note Index (47)

### Decision Records (8)

- `decisions/adr-002-payments.md` — 2026-03-20 — Going with Polar.sh over Stripe Connect
- `decisions/adr-001-database.md` — 2026-03-15 — We need a relational database...

### Meeting Notes (14)

### Retrospectives (6)

### Specs & PRDs (5)

### Research (4)

Qué detecta automáticamente:

Tipo de nota	Señales
Registros de decisión	Formato ADR (## Decision), "decidimos", "vamos con", "elegimos X sobre Y"
Notas de reunión	Attendees:, Action items:, nombre de archivo: standup, sync, 1on1
Retrospectivas	"Qué salió bien", "Dejar de hacer", nombre de archivo: retro, retrospective
Especificaciones / PRDs	## Goals, ## Requirements, nombre de archivo: prd, spec, roadmap
Investigación	nombre de archivo: research, analysis, benchmark, comparison
Registros de sesión	nombre de archivo: session, daily, weekly

Compatibilidad:

• Bóvedas Obsidian (frontmatter YAML, [[backlinks]], #tags)
• Exportaciones de Notion (archivos .md con frontmatter)
• Herramientas ADR (adr-tools, Log4brains, markdown sin procesar)
• Cualquier carpeta de archivos markdown

Uso conjunto:

Read .codesight/CODESIGHT.md   → what the code does
Read .codesight/KNOWLEDGE.md   → why decisions were made

CI: añade npx codesight --mode knowledge junto a tu paso existente de codesight. Ambos archivos se mantienen actualizados en cada push.

Benchmarks (Proyectos Reales)

Cada número a continuación proviene de ejecutar codesight en bases de código de producción reales — tanto proyectos SaaS pequeños (v1.6.2) como plataformas open-source grandes con 4K–10K+ archivos (v1.6.4). Los tokens de salida se miden desde el tamaño real del archivo (caracteres / 4). Los tokens de exploración se estiman a partir de lo extraído — rutas × 400, modelos × 300, componentes × 250, etc. Los recuentos de rutas y modelos se verifican contra los archivos fuente reales.

Reducción de Tokens en Tres Niveles

codesight ahorra tokens en dos capas distintas. La wiki (v1.6.2) añade una segunda capa sobre los ahorros base:

Proyecto	Exploración manual	Escaneo codesight	codesight --wiki (específico)	Reducción total
SaaS A	46,020 tokens	3,936 tokens (11.7x)	~550 tokens	83.7x
SaaS B	26,130 tokens	3,629 tokens (7.2x)	~440 tokens	59.4x
SaaS C	47,450 tokens	4,162 tokens (11.4x)	~360 tokens	131.8x

Reducción combinada promedio: 91x. El número "específico" de la wiki = leer index.md al inicio de la sesión (~200 tokens) + un artículo relevante (~160-350 tokens según el proyecto). Tu IA nunca carga el mapa de contexto completo para preguntas específicas.

Las dos capas de ahorro son independientes y se combinan:

Capa 1 — escaneo codesight elimina la exploración manual de archivos. En lugar de que tu IA ejecute glob/grep/read en 40-138 archivos para entender el proyecto, lee un mapa precompilado.

Capa 2 — --wiki elimina la carga del mapa completo para cada pregunta. En lugar de cargar 3K-5K tokens de contexto completo al inicio de la sesión, tu IA lee un índice de 200 tokens y extrae el artículo relevante (~160-350 tokens) para cada pregunta.

Without codesight:   AI reads 26K-47K tokens per session exploring files
With codesight:      AI reads ~3K-5K tokens (the compiled map)
With --wiki:         AI reads ~200 tokens at start + ~300 per targeted question

Resultados del Escaneo Base

Proyecto	Stack	Archivos	Rutas	Modelos	Componentes	Tokens de Salida	Tokens de Exploración	Ahorro	Tiempo de Escaneo
SaaS A	Hono + Drizzle	138	38	12	0	3,936	46,020	11.7x	186ms
SaaS B	Hono + Drizzle, 3 workspaces	53	17	8	10	3,629	26,130	7.2x	201ms
SaaS C	FastAPI + MongoDB	40	56	0	0	4,162	47,450	11.4x	890ms

SaaS C tiene 0 modelos porque usa MongoDB — no hay declaraciones ORM SQL para que codesight las analice. Esto es detección correcta, no un falso negativo.

Benchmark OSS Multi-Lenguaje (v1.6.7)

Probado contra bases de código open-source reales que abarcan todos los lenguajes y frameworks compatibles. Los tokens de salida se miden desde el tamaño real del archivo. Los tokens de exploración se estiman (rutas×400 + modelos×300 + componentes×250 + multiplicador de revisión). Cero falsos positivos en todas las pruebas.

Lenguaje	Stack	Archivos	Rutas	Modelos	Componentes	Tokens de salida	Exploración estimada	Ahorro
TypeScript · Next.js	Next.js + tRPC + Prisma · 110+ workspaces	7,509	479	173	1,309	158,660	~1,485,000	~9x
TypeScript · NestJS	NestJS + TypeORM + Mongoose	162	19	8	0	5,300	~67,500	~12.7x
TypeScript · Hono	Hono	—	8	0	0	—	—	✓
TypeScript · Remix	Remix + Prisma	36	11	0	9	—	—	✓
TypeScript · SvelteKit	SvelteKit	—	0³	0	23	—	—	✓
TypeScript · Nuxt	Nuxt	141	8	0	64	—	—	✓
JavaScript · Express	Express + Mongoose	51	10	5	0	1,241	~20,800	~17x
Ruby · Rails	Rails + ActiveRecord	4,172	607	116	0	21,711	~386,100	~17.8x
PHP · Laravel	Laravel + Eloquent	3,896	652	59	0	30,739	~493,285	~16x
Python · Django	Django + pyproject.toml	4,232	7¹	56	0	83,842	~631,020	~7.5x
Python · Flask	Flask + SQLAlchemy	30	12	5	0	1,148	~16,705	~14.5x
Python · FastAPI	FastAPI + SQLModel (monorepo)	143	21	2	36	2,487	~38,090	~15.3x
Elixir · Phoenix	Phoenix + Ecto	1,406	198	54	0	9,589	~152,100	~15.9x
Go · Gin	Gin + GORM (enterprise app)	388	202	169	0	15,266	~262,730	~17.2x
Go · Echo	Echo	—	7	0	0	—	—	✓
Go · Fiber	Fiber	—	5	0	0	—	—	✓
Rust · Actix	actix-web	528	30	0	0	1,355	~27,170	~20x
Rust · Axum	Axum	—	6	0	0	—	—	✓
C# · ASP.NET	ASP.NET Core + Entity Framework Core	256	13	7	0	5,126	~63,570	~12.4x
Java · Spring	Spring Boot + Java (Maven)	47	16	0	0	319	~13,208	~41x²
Swift · SwiftUI	SwiftUI	388	0	0	62	7,499	~76,830	~10.2x
Swift · Vapor	Vapor backend	294	81	0	0	6,146	~95,160	~15.5x
Dart · Flutter	Flutter + go_router	204	10	0	89	8,500	~86,125	~10.1x

¹ El proyecto Django es GraphQL-first — 7 endpoints REST de utilidad detectados con precisión, 0 falsos positivos. ² Proporción alta en boilerplate pequeño: los metadatos de rutas de Spring Boot se comprimen muy bien. ³ La app SvelteKit RealWorld usa rutas de página (+page.svelte), no endpoints JSON API (+server.ts). 0 rutas es correcto.

Cómo se estiman los tokens de exploración: routes×400 + models×300 + components×250 + hot_files×150 + env_vars×30, multiplicado por un factor de revisita de 1.3, menos el tamaño de salida. Esto aproxima lo que una IA gastaría preguntando "¿qué rutas existen?", "muéstrame el esquema", etc. en una sesión de exploración manual. El recuento de tokens de salida es el tamaño real medido del archivo.

Desglose de Wiki (v1.6.2)

Proyecto	CODESIGHT.md completo	Solo índice de Wiki	Índice + 1 artículo	Artículos de Wiki generados
SaaS A	3,936 tokens	~200 tokens	~550 tokens	9
SaaS B	3,629 tokens	~200 tokens	~440 tokens	11
SaaS C	4,162 tokens	~200 tokens	~360 tokens	17

"¿Cómo funciona la autenticación?" — sin wiki: carga 3,945 tokens. Con wiki: lee auth.md (~350 tokens). Mejora de 11x por pregunta específica, 84x total vs. manual.

Precisión de Detección

Verificado contra archivos fuente reales. Los recuentos de rutas se contrastan con las definiciones de rutas; los modelos de esquema se contrastan con las declaraciones de tablas ORM.

Proyecto	Recall de Rutas	Recall de Esquema	Falsos Positivos	Método de Detección
SaaS A	38/43 (88%)	12/12 (100%)	0	Esquema: AST (Drizzle), Rutas: AST (Hono)
SaaS B	17/17 (100%)	8/8 (100%)	0	AST completo (Hono + Drizzle + React)
SaaS C	56/59 (~95%)	0/0 (correcto)	0	AST (FastAPI + MongoDB)

Las 5 rutas no detectadas de SaaS A usan url.match(/pattern/) dinámicos dentro de los manejadores de solicitudes — un patrón de desarrollador que el análisis estático no puede resolver en el momento del escaneo. Este es un límite inherente del análisis estático, no una brecha del framework. SaaS C no detectó un estimado de 3 de 59 rutas de FastAPI. Cero falsos positivos en los tres proyectos.

Precisión del Radio de Impacto

Probado en un SaaS de producción: cambiar el módulo de base de datos identificó correctamente:

• 5 archivos afectados en las capas de API, autenticación y servidor
• Todas las rutas que tocan la base de datos
• 12 modelos afectados (esquema completo)
• Profundidad BFS: 3 saltos a través del grafo de importaciones

Qué se Detecta

Medido en los tres proyectos de referencia:

Detector	SaaS A (138 archivos)	SaaS B (53 archivos)	SaaS C (40 archivos)
Rutas	38	17	56
Modelos de esquema	12	8	0
Componentes	0	10	0
Variables de entorno	12	7	15
Archivos calientes	20	20	20

---

Cómo Funciona

codesight ejecuta los 8 detectores en paralelo y luego escribe los resultados como markdown estructurado. La salida está diseñada para ser leída por una IA en una sola carga de archivo.

Qué Genera

.codesight/
  CODESIGHT.md     Combined context map (one file, full project understanding)
  routes.md        Every API route with method, path, params, and what it touches
  schema.md        Every database model with fields, types, keys, and relations
  components.md    Every UI component with its props
  libs.md          Every library export with function signatures
  config.md        Every env var (required vs default), config files, key deps
  middleware.md    Auth, rate limiting, CORS, validation, logging, error handlers
  graph.md         Which files import what and which break the most things if changed
  cicd.md          GitHub Actions / CircleCI pipelines (when present)
  githooks.md      lefthook / husky / raw .git/hooks (when present)
  skills.md        .claude/commands + .claude/skills (when present)
  report.html      Interactive visual dashboard (with --html or --open)

Los últimos tres provienen de plugins integrados que escanean los directorios de dotfiles (.github/, .husky/, .claude/) que la pasada principal omite. Se ejecutan automáticamente y permanecen silenciosos en proyectos sin esos archivos — por lo que solo agregan una sección cuando hay algo que reportar.

Precisión de AST

Cuando TypeScript está instalado en el proyecto que se escanea, codesight usa la API real del compilador de TypeScript para analizar tu código estructuralmente. Sin adivinanzas con regex.

Lo que el AST permite	Solo con Regex
Sigue cadenas de router.use('/prefix', subRouter)	Omite routers anidados
Combina @Controller('users') + @Get(':id') en /users/:id	Puede omitir el prefijo
Analiza el anidamiento de tRPC router({ users: userRouter })	Coincidencia línea por línea
Extrae tipos exactos de campos Drizzle de cadenas .primaryKey().notNull()	Coincidencia de patrones
Obtiene props de React de interfaces TypeScript y desestructuración	Regex en { prop }
Detecta middleware en cadenas de rutas: app.get('/path', auth, handler)	No capturado
Filtra llamadas que no son rutas como c.get('userId')	Puede dar falsos positivos

La detección por AST se reporta en la salida:

Analyzing... done (AST: 60 routes, 18 models, 16 components)

No se necesita configuración. Si TypeScript está en tu node_modules, el AST se activa automáticamente. Funciona con npm, yarn y pnpm (incluido el modo estricto). Vuelve a regex para proyectos que no son TypeScript o frameworks sin soporte de AST.

Frameworks con soporte de AST: Express, Hono, Fastify, Koa, Elysia (cadenas de rutas + middleware), NestJS (combinación de decoradores + guards), tRPC ( anidamiento de routers + tipos de procedimientos), Drizzle (cadenas de campos + relaciones), TypeORM (decoradores de entidades), React (props de interfaces + desestructuración + forwardRef/memo).

Plugins WASM de AST nativo (opt-in)

Por defecto, codesight usa sus extractores integrados (AST para TypeScript, regex para todo lo demás). Opta con --native-ast para especificar que se deben usar plugins WebAssembly para adquirir precisión de AST completa para archivos fuente que no son TypeScript:

npx codesight --native-ast                 # use every discovered plugin (additive)
npx codesight --native-ast=rust,go         # only these languages (authoritative for their files)
npx codesight --native-ast=none            # force off (overrides config)
npx codesight --native-ast-strict          # like --native-ast, but fail if a named plugin is missing
npx codesight --plugin-dir ./wasm          # extra directory to search for plugins

El envío a plugins WASM está impulsado por lenguaje: cada plugin se autodescribe (a través de una exportación describe()) las extensiones de archivo que maneja, por lo que cualquier lenguaje funciona — no solo los que tienen detectores integrados. Cuando ningún plugin maneja un archivo, la extracción integrada prevalece; con --native-ast sin configurar, el comportamiento es byte-idéntico al comportamiento existente de codesight.

El paquete npm de codesight no incluye plugins — son artefactos separados y opt-in. El proyecto publica plugins de referencia precompilados (Rust/ syn, Python/ruff, Go/go/parser) como activos de lanzamiento de GitHub con checksum; coloca los que quieras usar en ~/.codesight/plugins/ (o apunta --plugin-dir a ellos), luego actívalos con --native-ast. Alternativamente, puedes construir tu propio plugin para cualquier lenguaje según el contrato.

→ Contrato completo, reglas de descubrimiento y pasos de descarga/instalación: docs/wasm-plugins.md.

Plugins Integrados

Tres plugins de primera parte se ejecutan en cada escaneo y exponen contexto que la pasada principal omite porque vive en directorios de dotfiles saltados. Cada uno está inerte hasta que sus archivos objetivo existen, por lo que no cuestan nada en proyectos que no los usan:

Plugin	Lee	Salida
cicd	.github/workflows/, .circleci/	Disparadores de pipeline, trabajos, secretos, objetivos de despliegue
githooks	Config de lefthook / husky, .git/hooks/	Qué comandos se ejecutan en qué ciclo de vida de git
skills	.claude/commands/, .claude/skills/	Comandos slash / habilidades de agente disponibles + descripciones

Opta por excluir cualquiera de ellos por proyecto:

// codesight.config.js
export default {disableDetectors: ["cicd", "githooks", "skills"]};

Terraform es opt-in, no se carga automáticamente — deliberadamente alcanza fuera del directorio escaneado (repos ../infrastructure hermanos) y es más útil con un nombre de servicio explícito, por lo que permanece desactivado hasta que lo solicites:

// codesight.config.js
import {createTerraformPlugin} from "codesight/plugins/terraform";

export default {plugins: [createTerraformPlugin({infraPath: "../infra"})]};

Rutas

No solo rutas. Métodos, parámetros de URL, qué toca cada ruta (auth, base de datos, caché, pagos, IA, correo, colas) y dónde vive el manejador. Detecta rutas en más de 30 frameworks automáticamente.

Ejemplo de salida:

- `GET` `/api/users/me` [auth, db, cache]
- `PUT` `/api/users/me` [auth, db]
- `POST` `/api/projects` [auth, db, payment]
- `GET` `/api/projects/:id` params(id) [auth, db]
- `POST` `/webhooks/stripe` [db, payment]
- `GET` `/health`

Esquema

Modelos, campos, tipos, claves primarias, claves foráneas, restricciones únicas, relaciones. Analizado directamente desde tus definiciones de ORM mediante AST. No es necesario abrir archivos de migración.

Ejemplo de salida:

### user

- id: text (pk)
- name: text (required)
- email: text (unique, required)
- role: text (default, required)
- stripeCustomerId: text (fk)

### project

- id: uuid (default, pk)
- ownerId: text (fk, required)
- name: text (required)
- settings: jsonb (required)
- _relations_: ownerId -> user.id

Grafo de Dependencias

Los archivos más importados son los que más cosas rompen cuando cambian. codesight los encuentra y le dice a tu IA que tenga cuidado.

Ejemplo de salida:

## Most Imported Files (change these carefully)

- `src/types/index.ts` — imported by **20** files
- `src/db/index.ts` — imported by **12** files
- `src/lib/auth.ts` — imported by **8** files
- `src/lib/cache.ts` — imported by **6** files
- `src/lib/env.ts` — imported by **5** files

Radio de Explosión

BFS a través del grafo de importaciones encuentra todos los archivos, rutas, modelos y middleware afectados transitivamente.

npx codesight --blast src/db/index.ts

Ejemplo de salida:

  Blast Radius: src/db/index.ts
  Depth: 3 hops

  Affected files (10):
    src/api/users.ts
    src/api/projects.ts
    src/api/webhooks.ts
    src/auth/session.ts
    src/jobs/notifications.ts
    src/server.ts
    src/auth/index.ts
    src/jobs/cron.ts
    src/cli.ts
    src/index.ts

  Affected routes (33):
    GET /api/users/me — src/api/users.ts
    POST /api/projects — src/api/projects.ts
    POST /webhooks/stripe — src/api/webhooks.ts
    ...

  Affected models: user, session, account, project,
    subscription, notification, audit_log

Tu IA también puede consultar el radio de explosión a través del servidor MCP antes de hacer cambios.

Auditoría de Entorno

Cada variable de entorno en tu código, marcada como requerida o con valor predeterminado, con el archivo exacto donde se referencia.

Ejemplo de salida:

- `DATABASE_URL` **required** — .env.example
- `REDIS_URL` (has default) — .env.example
- `STRIPE_SECRET_KEY` **required** — src/lib/payments.ts
- `STRIPE_WEBHOOK_SECRET` **required** — .env.example
- `RESEND_API_KEY` **required** — .env.example
- `JWT_SECRET` **required** — src/lib/auth.ts

Benchmark de Tokens

Mira exactamente de dónde provienen tus ahorros de tokens:

npx codesight --benchmark

Ejemplo de salida (SaaS A — 138 archivos, Hono + Drizzle):

  Token Savings Breakdown:
  ┌──────────────────────────────────────────────────┐
  │ What codesight found         │ Exploration cost   │
  ├──────────────────────────────┼────────────────────┤
  │  38 routes                   │ ~15,200 tokens     │
  │  12 schema models            │ ~ 3,600 tokens     │
  │   0 components               │       0 tokens     │
  │  30 library files            │ ~ 6,000 tokens     │
  │  12 env vars                 │ ~ 1,200 tokens     │
  │   5 middleware               │ ~ 1,000 tokens     │
  │  20 hot files                │ ~ 3,000 tokens     │
  │ 138 files (search overhead)  │ ~11,040 tokens     │
  ├──────────────────────────────┼────────────────────┤
  │ codesight output             │ ~ 3,936 tokens     │
  │ Manual exploration (1.3x)    │ ~46,020 tokens     │
  │ SAVED PER CONVERSATION       │ ~42,084 tokens     │
  └──────────────────────────────┴────────────────────┘

Cómo se Calculan los Ahorros de Tokens

Cada tipo de detector se asigna a un costo de tokens medido que una IA gastaría para descubrir la misma información manualmente:

Lo que encuentra codesight	Tokens ahorrados por elemento	Por qué
Cada ruta	~400 tokens	La IA lee el archivo del manejador, busca la ruta, lee middleware
Cada modelo de esquema	~300 tokens	La IA abre archivos de migración/ORM, analiza campos manualmente
Cada componente	~250 tokens	La IA abre archivos de componentes, lee tipos de props
Cada exportación de librería	~200 tokens	La IA busca exportaciones, lee firmas
Cada variable de entorno	~100 tokens	La IA busca process.env, lee archivos .env
Cada archivo escaneado	~80 tokens	La IA ejecuta operaciones glob/grep para encontrar archivos relevantes

El multiplicador de 1.3x tiene en cuenta que la IA revisita archivos durante conversaciones de múltiples turnos. Estas estimaciones son conservadoras. Un desarrollador verificó manualmente que Claude Code gasta 40-70K tokens explorando los mismos proyectos que codesight resume en 3-5K tokens.

Roku / BrightScript / SceneGraph

codesight trata los canales de Roku como proyectos de primera clase. El archivo manifest en la raíz del canal ancla la detección — el mismo archivo que Roku usa para identificar un canal, por lo que no se necesita configuración para el caso común.

Diseño estándar de canal único (alrededor del 90% de los repositorios de Roku, coincide con la plantilla de inicio de la documentación de Roku y proyectos como rokucommunity/brighterscript-template):

/
  manifest
  source/         # Main.brs + shared .brs libraries
  components/     # *.xml + paired *.brs component handlers
  images/

codesight también reconoce el diseño rokucommunity/brighterscript-template donde el canal vive bajo src/ y la raíz lleva un bsconfig.json para herramientas de BrighterScript.

Diseño de monorepo multicanal (menos común — usado por bases de código más grandes que publican varios canales de marca desde un solo repositorio con roku-deploy + gulp para fusionar una capa compartida de common/ con activos por canal en el momento de la compilación):

/
  package.json      # depends on roku-deploy, gulp
  gulpfile.js
  src/apps/
    common/         # shared layer, merged into every channel at build
    creatorA/
      manifest
    creatorB/
      manifest

Esto se detecta mediante una señal estructural estricta: sin manifest en la raíz, roku-deploy en dependencias, y un directorio common/ con al menos 2 directorios hermanos que cada uno tenga su propio manifest. Cuando la señal coincide, cada canal (más common/) se registra como un espacio de trabajo.

Mapeos al modelo de datos de codesight

Concepto de codesight	Equivalente en Roku
Rutas	Pantallas — cada elemento hijo con un id declarado en el <children> del XML de la escena. method = VIEW por defecto, actualizado a MODAL si un sitio de llamada de navegación pasa un true literal como segundo argumento.
Esquema	Cada XML de componente SceneGraph cuyo <interface> tenga al menos un <field> — el contrato tipado es el modelo.
Componentes	Cada XML de <component name="..." extends="..."> (vistas, tareas, escenas, modales). Props = campos de interfaz.
Librerías	Archivos .brs / .bs fuera de components/ — function/sub de nivel superior más class / namespace / enum / interface de BrighterScript.
Middleware	Suscripciones observeField, registros m.global.AddField. BugsnagTask / RudderstackTask reconocidos cuando están presentes.
Dependencias	Incluye <script uri="pkg:/..." /> en XML de componentes + import "pkg:/..." en .bs.
Eventos	Campos observados (system: scenegraph-observer) y nombres de eventos de Rudderstack (system: rudderstack).
Configuración	Las líneas clave/valor de manifest de Roku presentadas como pseudo variables de entorno manifest.<name>.

Ayudantes de navegación configurables

Muchos proyectos de Roku usan un ayudante personalizado para cambiar la pantalla visible (los nombres varían: ShowScreen, pushScreen, NavigateTo, showView, etc.). Estos se usan como enriquecimiento opcional para etiquetar rutas como MODAL. Los valores predeterminados cubren las convenciones comunes; anula con rokuScreenHelpers en tu configuración de codesight si tu proyecto usa un nombre diferente:

{
  "rokuScreenHelpers": [
    "Router.push",
    "openScreen"
  ]
}

Las rutas aún se detectan desde <children> incluso cuando no hay ayudante presente o cuando ningún sitio de llamada coincide.

Ejemplo de salida

- `VIEW` `/homeView` — components/views/HomeView.xml
- `VIEW` `/detailView` — components/views/DetailView.xml
- `MODAL` `/errorModal` — components/modals/ErrorModal.xml

### DataTask

- requestUrl: string
- response: object

Stacks Soportados

Categoría	Soportado
Rutas	Hono, Express, Fastify, Next.js (App + Pages), Koa, NestJS, tRPC, Elysia, AdonisJS, SvelteKit, Remix, Nuxt, FastAPI, Flask, Django, Go (net/http, Gin, Fiber, Echo, Chi), Rails, Phoenix, Spring Boot, Ktor, Actix, Axum, Laravel, ASP.NET Core (controllers + minimal API), Vapor, Flutter (go_router), Roku SceneGraph (screens via ShowScreen), raw http.createServer
Eventos	Colas BullMQ, tareas Celery, temas Kafka, Redis pub/sub, Socket.io, EventEmitter, observadores SceneGraph, Rudderstack
Esquema	Drizzle, Prisma, TypeORM, Mongoose, Sequelize, SQLAlchemy, Django ORM, ActiveRecord, Ecto, Eloquent, Entity Framework, Exposed, Room, contratos SceneGraph <interface> (14 ORMs)
Componentes	React, Vue, Svelte, widgets Flutter (StatelessWidget, StatefulWidget, ConsumerWidget), vistas SwiftUI (filtra automáticamente shadcn/ui y primitivas Radix), componentes Roku SceneGraph
Librerías	TypeScript, JavaScript, Python, Go, Dart, Swift, C#, PHP, BrightScript, BrighterScript (exportaciones con firmas de funciones)
Middleware	Auth, limitación de velocidad, CORS, validación, registro, manejadores de errores, observadores SceneGraph + campos m.global
Dependencias	Grafo de importaciones con detección de archivos calientes (más importados = mayor radio de explosión); declaraciones SceneGraph <script uri="pkg:/..."> y BrighterScript import
Contratos	Parámetros de URL, tipos de solicitud, tipos de respuesta de manejadores de rutas
Monorepos	pnpm, npm, yarn workspaces + espacios de trabajo de lenguaje mixto (p. ej. Next.js + Laravel, SwiftUI + Vapor, Roku multicanal bajo src/apps/<creator>/)
Lenguajes	TypeScript, JavaScript, Python, Go, Ruby, Elixir, Java, Kotlin, Rust, PHP, Dart, Swift, C#, BrightScript/BrighterScript

Generación de Configuración de IA

npx codesight --init

Genera archivos de instrucciones listos para usar para cada herramienta importante de codificación con IA a la vez:

Archivo	Herramienta
CLAUDE.md	Claude Code
.cursorrules	Cursor
.github/copilot-instructions.md	GitHub Copilot
codex.md	OpenAI Codex CLI
AGENTS.md	OpenAI Codex agents
Cada archivo viene prellenado con el stack de tu proyecto, la arquitectura, los archivos de alto impacto y las variables de entorno requeridas. Tu IA lo lee al iniciar y
comienza con contexto completo desde el primer mensaje.

Servidor MCP (14 herramientas)

npx codesight --mcp

Se ejecuta como un servidor de Protocolo de Contexto de Modelo (MCP). Claude Code y Cursor lo llaman directamente para obtener contexto del proyecto bajo demanda.

{
  "mcpServers": {
    "codesight": {
      "command": "npx",
      "args": [
        "codesight",
        "--mcp"
      ]
    }
  }
}

OpenAI Codex CLI (~/.codex/config.toml):

[mcp_servers.codesight]
command = "npx"
args = ["codesight", "--mcp"]
startup_timeout_sec = 60

Nota sobre el tiempo de espera de Codex: npx tiene que resolver el paquete en la primera ejecución, lo que puede superar el tiempo de espera predeterminado de 30 segundos. Establece startup_timeout_sec = 60 o instala globalmente (npm install -g codesight) y usa command = "codesight" en su lugar — las instalaciones globales inician significativamente más rápido.

Herramienta	Qué hace
codesight_get_wiki_index	Catálogo wiki (~200 tokens) — se lee al inicio de la sesión
codesight_get_wiki_article	Lee un artículo wiki por nombre: auth, database, payments, etc.
codesight_lint_wiki	Verificación de salud: artículos huérfanos, enlaces cruzados faltantes
codesight_scan	Escaneo completo del proyecto (~3K-5K tokens)
codesight_get_summary	Resumen compacto (~500 tokens)
codesight_get_routes	Rutas filtradas por prefijo, etiqueta o método
codesight_get_schema	Esquema filtrado por nombre de modelo
codesight_get_blast_radius	Análisis de impacto antes de modificar un archivo
codesight_get_env	Variables de entorno (filtro: solo requeridas)
codesight_get_hot_files	Archivos más importados con límite configurable
codesight_get_events	Eventos en segundo plano: colas BullMQ, tareas Celery, temas Kafka, Redis pub/sub, EventEmitter
codesight_get_coverage	Mapa de cobertura de pruebas: qué rutas y modelos tienen archivos de prueba
codesight_get_knowledge	Mapa de conocimiento desde --mode knowledge: decisiones, preguntas abiertas, temas, índice de notas
codesight_refresh	Forzar re-escaneo (los resultados se almacenan en caché por sesión)

Tu IA solicita exactamente lo que necesita en lugar de cargar todo el mapa de contexto. El almacenamiento en caché de sesión significa que la primera llamada escanea, las llamadas posteriores regresan al instante.

Perfiles de herramientas de IA

npx codesight --profile claude-code
npx codesight --profile cursor
npx codesight --profile codex
npx codesight --profile copilot
npx codesight --profile windsurf

Genera un archivo de configuración optimizado para una herramienta de IA específica. Cada perfil incluye el resumen de tu proyecto, información del stack, archivos de alto impacto, variables de entorno requeridas e instrucciones específicas de la herramienta sobre cómo usar las salidas de codesight. Para Claude Code, esto incluye instrucciones de uso de herramientas MCP. Para Cursor, apunta a los archivos correctos de codesight. Cada perfil escribe en el archivo correcto para esa herramienta.

Informe visual

npx codesight --open

Abre un panel HTML interactivo en tu navegador. Tabla de rutas con insignias de método y etiquetas. Tarjetas de esquema con campos y relaciones. Archivos calientes de dependencias con barras de impacto. Auditoría de variables de entorno. Desglose de ahorro de tokens. Útil para la incorporación o simplemente para ver tu proyecto desde una vista general.

Acción de GitHub

Agrega a tu canal de CI para mantener el contexto actualizado en cada push:

name: codesight
on: [ push ]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install -g codesight && codesight
      - uses: actions/upload-artifact@v4
        with:
          name: codesight
          path: .codesight/

Modo de observación y gancho de Git

El modo de observación re-escanea automáticamente cuando tu código cambia:

npx codesight --watch

Solo se activa en archivos de código fuente y configuración (.ts, .js, .py, .go, .prisma, .env, etc.). Ignora node_modules, la salida de compilación y archivos que no son código. Muestra qué archivos cambiaron antes de cada re-escaneo. Tu configuración (detectores deshabilitados, plugins) se conserva entre re-escaneos.

El gancho de Git regenera el contexto en cada commit:

npx codesight --hook

El contexto se mantiene actualizado sin que tengas que pensar en ello.

Todas las opciones

npx codesight                              # Scan current directory
npx codesight ./my-project                 # Scan specific directory
npx codesight --wiki                       # Generate wiki knowledge base
npx codesight --init                       # Generate AI config files
npx codesight --open                       # Open visual HTML report
npx codesight --html                       # Generate HTML report without opening
npx codesight --mcp                        # Start MCP server (14 tools)
npx codesight --blast src/lib/db.ts        # Show blast radius for a file
npx codesight --profile claude-code        # Optimized config for specific tool
npx codesight --watch                      # Watch mode (add --wiki to auto-regenerate wiki)
npx codesight --wiki --watch               # Watch + auto-regenerate wiki on changes
npx codesight --hook                       # Install git pre-commit hook (includes wiki)
npx codesight --benchmark                  # Detailed token savings breakdown
npx codesight --json                       # Output as JSON
npx codesight --mode knowledge             # Map .md knowledge base → KNOWLEDGE.md
npx codesight --mode knowledge ~/vault     # Map Obsidian vault or any .md folder
npx codesight --max-tokens 50000           # Trim output to fit token budget
npx codesight --since HEAD~5               # Show routes from last 5 commits only
npx codesight -o .ai-context               # Custom output directory
npx codesight -d 5                         # Limit directory depth

Cómo se compara

	codesight	Herramientas de concatenación de archivos	Herramientas basadas en AST (p. ej., code-review-graph)
Análisis	AST (compilador de TypeScript) + respaldo de regex	Ninguno	Tree-sitter + SQLite
Reducción de tokens	7x-12x escaneo base; 60-131x con consultas wiki dirigidas	1x (vuelca todo)	8x reportado
Detección de rutas	30+ frameworks, auto-detectado	Ninguno	Limitado
Análisis de esquemas	14 ORMs con tipos de campo y relaciones	Ninguno	Varía
Radio de impacto	BFS a través del grafo de importaciones	Ninguno	Sí
Perfiles de herramientas de IA	5 herramientas (Claude, Cursor, Codex, Copilot, Windsurf)	Ninguno	Auto-detección
Herramientas MCP	14 herramientas especializadas con caché de sesión	Ninguno	22 herramientas
Configuración	npx codesight (cero dependencias, cero configuración)	Copiar/pegar	pip install + dependencias opcionales
Dependencias	Cero (toma prestado TS de tu proyecto)	Varía	Tree-sitter, SQLite, NetworkX, etc.
Lenguaje	TypeScript (cero dependencias de ejecución)	Varía	Python
Tiempo de escaneo	185-290ms (pequeño), 0.9-2.8s (10K archivos)	Varía	Menos de 2s reportado

codesight está diseñado específicamente para el problema que la mayoría de los desarrolladores realmente tienen: darle a su asistente de IA suficiente contexto para ser útil sin desperdiciar tokens en exploración de archivos. Se centra en la extracción estructurada (rutas, esquemas, componentes, dependencias) en lugar de análisis de grafos de código de propósito general.

Contribuciones

git clone https://github.com/Houseofmvps/codesight.git
cd codesight
pnpm install
pnpm dev              # Run locally
pnpm build            # Compile TypeScript
pnpm test             # Run 149 tests

Los PRs son bienvenidos. Abre un issue primero para cambios grandes.

Licencia

MIT

---