codesight

---

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

Funciona Com

Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Windsurf, Cline, Aider e qualquer coisa que leia markdown.

Instalação

npx codesight

É isso. Execute na raiz de qualquer projeto. Sem configuração, sem setup, sem chaves de 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 Conhecimento Wiki (v1.6.2)

Inspirado no padrão de wiki LLM do Karpathy — mas compilado a partir de AST, não por um LLM. Zero chamadas de API. 200ms.

npx codesight --wiki

Gera .codesight/wiki/ — uma base de conhecimento persistente do seu código que sobrevive a todas as sessões:

.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 que isso reduz ainda mais o uso de tokens:

Em vez de carregar o mapa de contexto completo de 5K tokens em todas as conversas, seu IA lê um artigo direcionado:

Pergunta	Sem wiki	Com wiki
"Como funciona o auth?"	~12K tokens (lê 8+ arquivos)	~300 tokens (auth.md)
"Quais modelos existem?"	~5K tokens (CODESIGHT.md)	~400 tokens (database.md)
Início de nova sessão	~5K tokens (recarga completa)	~200 tokens (index.md)

Persistente entre sessões. A wiki vive em .codesight/wiki/, commitada no git. Cada nova sessão do Claude Code, Cursor ou Codex começa com conhecimento completo do código desde a primeira mensagem.

Regeneração automática. Use --watch para manter a wiki atualizada enquanto você codifica. Use --hook para regenerar a cada commit.

3 novas ferramentas MCP para acesso à wiki:

Ferramenta	O que faz
codesight_get_wiki_index	Obtém o catálogo da wiki (~200 tokens) no início da sessão
codesight_get_wiki_article	Lê um artigo pelo nome: auth, database, payments, etc.
codesight_lint_wiki	Verificação de saúde: artigos órfãos, links cruzados ausentes, conteúdo desatualizado

A diferença-chave das ferramentas de wiki de uso geral: a codesight já conhece suas rotas, schema, raio de impacto e middleware a partir da AST — nenhum LLM é necessário para extrair a estrutura do código. A wiki é uma camada narrativa sobre dados que seu código já contém.

Modo Conhecimento (v1.9.3)

Não só código — suas decisões, notas de reunião, ADRs e retrospectivas carregam tanto contexto quanto o próprio código. --mode knowledge mapeia eles da mesma forma que a codesight mapeia 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

Gera .codesight/KNOWLEDGE.md — um primer 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)

O que detecta automaticamente:

Tipo de nota	Sinais
Registros de decisão	Formato ADR (## Decision), "decidimos", "vamos com", "escolhemos X em vez de Y"
Notas de reunião	Attendees:, Action items:, nome de arquivo: standup, sync, 1on1
Retrospectivas	"O que deu certo", "Parar de fazer", nome de arquivo: retro, retrospective
Specs / PRDs	## Goals, ## Requirements, nome de arquivo: prd, spec, roadmap
Pesquisa	nome de arquivo: research, analysis, benchmark, comparison
Logs de sessão	nome de arquivo: session, daily, weekly

Suporta:

• Vaults do Obsidian (frontmatter YAML, [[backlinks]], #tags)
• Exportações do Notion (arquivos .md com frontmatter)
• Ferramentas de ADR (adr-tools, Log4brains, markdown puro)
• Qualquer pasta de arquivos markdown

Usados juntos:

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

CI: adicione npx codesight --mode knowledge junto ao seu passo existente da codesight. Ambos os arquivos permanecem atualizados a cada push.

Benchmarks (Projetos Reais)

Cada número abaixo vem de executar a codesight em bases de código de produção reais — tanto projetos SaaS pequenos (v1.6.2) quanto plataformas open-source grandes com 4K–10K+ arquivos (v1.6.4). Tokens de saída são medidos a partir do tamanho real do arquivo (caracteres / 4). Tokens de exploração são estimados pelo que foi extraído — rotas × 400, modelos × 300, componentes × 250, etc. Contagens de rotas e modelos são verificadas nos arquivos-fonte reais.

Redução de Tokens em Três Níveis

a codesight economiza tokens em duas camadas distintas. A wiki (v1.6.2) adiciona uma segunda camada sobre a economia base:

Projeto	Exploração manual	Scan da codesight	codesight --wiki (direcionado)	Redução 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

Redução média combinada: 91x. O número "direcionado" da wiki = ler index.md no início da sessão (~200 tokens) + um artigo relevante (~160-350 tokens dependendo do projeto). Sua IA nunca carrega o mapa de contexto completo para perguntas direcionadas.

As duas camadas de economia são independentes e se acumulam:

Camada 1 — scan da codesight elimina a exploração manual de arquivos. Em vez de sua IA executar glob/grep/read em 40-138 arquivos para entender o projeto, ela lê um mapa pré-compilado.

Camada 2 — --wiki elimina o carregamento do mapa completo para cada pergunta. Em vez de carregar 3K-5K tokens de contexto completo no início da sessão, sua IA lê um índice de 200 tokens e puxa o artigo relevante (~160-350 tokens) para cada pergunta.

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 do Scan Base

Projeto	Stack	Arquivos	Rotas	Modelos	Componentes	Tokens de Saída	Tokens de Exploração	Economia	Tempo de Scan
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

O SaaS C tem 0 modelos porque usa MongoDB — nenhuma declaração de ORM SQL para a codesight parsear. Isso é detecção correta, não um falso negativo.

Benchmark OSS Multi-Linguagem (v1.6.7)

Testado em bases de código open-source reais cobrindo todas as linguagens e frameworks suportados. Tokens de saída são medidos a partir do tamanho real do arquivo. Tokens de exploração são estimados (rotas×400 + modelos×300 + componentes×250 + multiplicador de revisita). Zero falsos positivos em todos os testes.| Idioma | Pilha (Stack) | Arquivos | Rotas | Modelos | Componentes | Tokens de saída | Exploração estimada | Economia | |------------------------|---------------------------------------|----------|-------|---------|--------------|-------------------|---------------------|-------------| | 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 |

¹ Projeto Django é GraphQL-first — 7 endpoints utilitários REST detectados com precisão, 0 falsos positivos. ² Proporção alta em boilerplate pequeno: metadados de rotas do Spring Boot comprimem muito bem. ³ O app SvelteKit RealWorld usa rotas de página (+page.svelte), não endpoints JSON API (+server.ts). 0 rotas está correto.

Como os tokens de exploração são estimados: routes×400 + models×300 + components×250 + hot_files×150 + env_vars×30, vezes um multiplicador de revisita de 1.3, menos o tamanho da saída. Isso aproxima o que uma IA gastaria perguntando "quais rotas existem?", "mostre o schema", etc. em uma sessão de exploração manual. A contagem de tokens de saída é o tamanho real medido do arquivo.

Detalhamento da Wiki (v1.6.2)

Projeto	CODESIGHT.md completo	Somente índice da wiki	Índice + 1 artigo	Artigos da wiki gerados
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

"Como funciona a autenticação?" — sem wiki: carrega 3.945 tokens. Com wiki: lê auth.md (~350 tokens). Melhora de 11x por pergunta direcionada, 84x total vs manual.

Precisão de Detecção

Verificado contra arquivos-fonte reais. As contagens de rotas são verificadas cruzadamente com definições de rotas; os modelos de schema são verificados cruzadamente com declarações de tabela ORM.

Projeto	Recall de Rotas	Recall de Schema	Falsos Positivos	Método de Detecção
SaaS A	38/43 (88%)	12/12 (100%)	0	Schema: AST (Drizzle), Rotas: AST (Hono)
SaaS B	17/17 (100%)	8/8 (100%)	0	AST completo (Hono + Drizzle + React)
SaaS C	56/59 (~95%)	0/0 (correto)	0	AST (FastAPI + MongoDB)

As 5 rotas perdidas do SaaS A usam url.match(/pattern/) dinâmico dentro de manipuladores de requisição — um padrão de desenvolvedor que análise estática não consegue resolver no momento da varredura. Este é um limite inerente da análise estática, não uma lacuna do framework. SaaS C perdeu aproximadamente 3 de 59 rotas FastAPI. Zero falsos positivos em todos os três projetos.

Precisão do Raio de Impacto

Testado em um SaaS de produção: alterar o módulo de banco de dados identificou corretamente:

• 5 arquivos afetados nas camadas de API, auth e servidor
• Todas as rotas que tocam o banco de dados
• 12 modelos afetados (schema completo)
• Profundidade BFS: 3 saltos pelo grafo de importações

O Que É Detectado

Medido nos três projetos de referência:

Detector	SaaS A (138 arquivos)	SaaS B (53 arquivos)	SaaS C (40 arquivos)
Rotas	38	17	56
Modelos de schema	12	8	0
Componentes	0	10	0
Variáveis de ambiente	12	7	15
Arquivos quentes	20	20	20

---

Como Funciona

codesight executa todos os 8 detectores em paralelo e depois escreve os resultados como markdown estruturado. A saída é projetada para ser lida por uma IA em um único carregamento de arquivo.

O Que Ele Gera

.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)

Os três últimos vêm de plugins integrados que escaneiam os diretórios de dotfiles (.github/, .husky/, .claude/) que a passagem principal ignora. Eles são executados automaticamente e permanecem silenciosos em projetos sem esses arquivos — então só adicionam uma seção quando há algo para relatar.

Precisão do AST

Quando o TypeScript está instalado no projeto sendo escaneado, o codesight usa a API real do compilador TypeScript para analisar seu código estruturalmente. Sem adivinhação por regex.

O que o AST permite	Somente regex
Segue cadeias de router.use('/prefix', subRouter)	Perde roteadores aninhados
Combina @Controller('users') + @Get(':id') em /users/:id	Pode perder o prefixo
Analisa router({ users: userRouter }) aninhamento de tRPC	Correspondência linha por linha
Extrai tipos exatos de campos Drizzle de cadeias de .primaryKey().notNull()	Correspondência de padrões
Obtém props React de interfaces TypeScript e desestruturação	Regex em { prop }
Detecta middleware em cadeias de rotas: app.get('/path', auth, handler)	Não capturado
Filtra chamadas não relacionadas a rotas como c.get('userId')	Pode gerar falso positivo

A detecção AST é relatada na saída:

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

Nenhuma configuração necessária. Se o TypeScript estiver no seu node_modules, o AST é ativado automaticamente. Funciona com npm, yarn e pnpm (incluindo modo estrito). Reverte para regex em projetos não-TypeScript ou frameworks sem suporte a AST.

Frameworks com suporte a AST: Express, Hono, Fastify, Koa, Elysia (cadeias de rotas + middleware), NestJS (combinação de decoradores + guards), tRPC ( aninhamento de roteadores + tipos de procedimentos), Drizzle (cadeias de campos + relações), TypeORM (decoradores de entidades), React (props de interfaces + desestruturação + forwardRef/memo).

Plugins WASM Native-AST (opt-in)

Por padrão, o codesight usa seus extratores integrados (AST para TypeScript, regex para todo o resto). Opte com --native-ast para especificar que plugins WebAssembly devem ser usados para adquirir precisão total de AST para arquivos-fonte não-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

O despacho para plugins WASM é orientado por linguagem: cada plugin se autodescreve (via uma exportação describe()) as extensões de arquivo que ele manipula, então qualquer linguagem funciona — não apenas aquelas com detectores integrados. Onde nenhum plugin manipula um arquivo, a extração integrada permanece; com --native-ast não definido, o comportamento é byte-idêntico ao comportamento existente do codesight.

O pacote npm do codesight não acompanha plugins — eles são artefatos separados e opt-in. O projeto publica plugins de referência pré-construídos (Rust/ syn, Python/ruff, Go/go/parser) como ativos de release GitHub com soma de verificação; coloque os que deseja usar em ~/.codesight/plugins/ (ou aponte --plugin-dir para eles), então habilite com --native-ast. Alternativamente, você pode criar seu próprio plugin para qualquer linguagem contra o contrato.

→ Contrato completo, regras de descoberta e etapas de download/instalação: docs/wasm-plugins.md.

Plugins Integrados

Três plugins de terceiros são executados em cada varredura e trazem contexto que a passagem principal perde porque ele vive em diretórios de dotfiles ignorados. Cada um fica inativo até que seus arquivos-alvo existam, então não custam nada em projetos que não os usam:

Plugin	Lê	Saída
cicd	.github/workflows/, .circleci/	Gatilhos de pipeline, jobs, segredos, alvos de deploy
githooks	config do lefthook / husky, .git/hooks/	Quais comandos rodam em qual ciclo de vida do git
skills	.claude/commands/, .claude/skills/	Comandos slash disponíveis / habilidades de agent + descrições

Desative qualquer um deles por projeto:

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

Terraform é opt-in, não carregado automaticamente — ele deliberadamente alcança fora do diretório escaneado (repositórios irmãos ../infrastructure) e é mais útil com um nome de serviço explícito, então permanece desligado até você solicitá-lo:

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

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

Rotas

Não apenas caminhos. Métodos, parâmetros de URL, o que cada rota toca (auth, banco de dados, cache, pagamentos, IA, e-mail, filas) e onde o handler vive. Detecta rotas em mais de 30 frameworks automaticamente.

Exemplo de saída:

- `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, chaves primárias, chaves estrangeiras, restrições de unicidade, relações. Analisados diretamente das suas definições de ORM via AST. Sem necessidade de abrir arquivos de migração.

Exemplo de saída:

### 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 Dependências

Os arquivos mais importados são os que quebram mais coisas quando alterados. O codesight os encontra e avisa sua IA para ter cuidado.

Exemplo de saída:

## 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

Raio de Impacto

BFS através do grafo de importação encontra todos os arquivos, rotas, modelos e middlewares afetados transitivamente.

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

Exemplo de saída:

  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

Sua IA também pode consultar o raio de impacto através do servidor MCP antes de fazer alterações.

Auditoria de Ambiente

Cada variável de ambiente em todo o seu código, marcada como obrigatória ou com padrão, com o arquivo exato onde é referenciada.

Exemplo de saída:

- `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

Veja exatamente de onde vêm suas economias de tokens:

npx codesight --benchmark

Exemplo de saída (SaaS A — 138 arquivos, 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     │
  └──────────────────────────────┴────────────────────┘

Como as Economias de Tokens São Calculadas

Cada tipo de detector mapeia para um custo de tokens medido que uma IA gastaria para descobrir a mesma informação manualmente:

O que o codesight encontra	Tokens economizados por item	Porquê
Cada rota	~400 tokens	A IA lê o arquivo do handler, busca o caminho, lê middlewares
Cada modelo de esquema	~300 tokens	A IA abre arquivos de migração/ORM, analisa campos manualmente
Cada componente	~250 tokens	A IA abre arquivos de componente, lê tipos de props
Cada exportação de biblioteca	~200 tokens	A IA busca exportações, lê assinaturas
Cada variável de ambiente	~100 tokens	A IA busca por process.env, lê arquivos .env
Cada arquivo escaneado	~80 tokens	A IA executa operações glob/grep para encontrar arquivos relevantes

O multiplicador de 1,3x considera a IA revisitando arquivos durante conversas de múltiplas etapas. Essas estimativas são conservadoras. Um desenvolvedor verificou manualmente que o Claude Code gasta de 40 a 70 mil tokens explorando os mesmos projetos que o codesight resume em 3 a 5 mil tokens.

Roku / BrightScript / SceneGraph

O codesight trata canais Roku como projetos de primeira classe. O arquivo manifest na raiz do canal ancora a detecção — o mesmo arquivo que o próprio Roku usa para identificar um canal, então nenhuma configuração é necessária para o caso comum.

Layout padrão de canal único (cerca de 90% dos repositórios Roku, corresponde ao modelo de introdução da documentação do Roku e a projetos como rokucommunity/brighterscript-template):

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

O codesight também reconhece o layout rokucommunity/brighterscript-template onde o canal fica em src/ e a raiz contém um bsconfig.json para ferramentas BrighterScript.

Layout de monorepo multicanal (menos comum — usado por bases de código maiores que distribuem vários canais de marca a partir de um repositório com roku-deploy + gulp para mesclar uma camada compartilhada common/ com ativos por canal no momento da compilação):

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

Isso é detectado por meio de um sinal estrutural estrito: nenhum manifest na raiz, roku-deploy nas dependências e um diretório common/ com pelo menos 2 diretórios irmãos que cada um tem seu próprio manifest. Quando o sinal corresponde, cada canal (mais common/) é registrado como um workspace.

Mapeamentos para o modelo de dados do codesight

Conceito do codesight	Equivalente Roku
Rotas	Telas — cada elemento filho com um id declarado no <children> do XML da cena. method = VIEW por padrão, atualizado para MODAL se um local de chamada de navegação passar um literal true como segundo argumento.
Esquema	Cada XML de componente SceneGraph cujo <interface> tem pelo menos um <field> — o contrato tipado é o modelo.
Componentes	Cada XML <component name="..." extends="..."> (views, tasks, scenes, modals). Props = campos de interface.
Bibliotecas	Arquivos .brs / .bs fora de components/ — function/sub de nível superior mais BrighterScript class / namespace / enum / interface.
Middleware	Assinaturas observeField, registros m.global.AddField. BugsnagTask / RudderstackTask reconhecidos quando presentes.
Dependências	Inclusões <script uri="pkg:/..." /> no XML do componente + import "pkg:/..." em .bs.
Eventos	Campos observados (system: scenegraph-observer) e nomes de eventos Rudderstack (system: rudderstack).
Config	As linhas de chave/valor manifest do Roku exibidas como pseudo variáveis de ambiente manifest.<name>.

Auxiliares de navegação configuráveis

Muitos projetos Roku usam um auxiliar personalizado para alternar a tela visível (os nomes variam: ShowScreen, pushScreen, NavigateTo, showView, etc.). Eles são usados como enriquecimento opcional para marcar rotas como MODAL. Os padrões cobrem as convenções comuns; substitua com rokuScreenHelpers na sua configuração do codesight se o seu projeto usar um nome diferente:

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

As rotas ainda são detectadas a partir de <children> mesmo quando nenhum auxiliar está presente ou quando nenhum local de chamada corresponde.

Exemplo de saída

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

### DataTask

- requestUrl: string
- response: object

Stacks Suportadas

Categoria	Suportado
Rotas	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 (telas via ShowScreen), http.createServer puro
Eventos	Filas BullMQ, tarefas Celery, tópicos 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), views SwiftUI (filtra automaticamente shadcn/ui e primitivas Radix), componentes Roku SceneGraph
Bibliotecas	TypeScript, JavaScript, Python, Go, Dart, Swift, C#, PHP, BrightScript, BrighterScript (exportações com assinaturas de função)
Middleware	Auth, limitação de taxa, CORS, validação, logging, manipuladores de erro, observadores SceneGraph + campos m.global
Dependências	Grafo de importação com detecção de arquivos quentes (mais importados = maior raio de impacto); declarações SceneGraph <script uri="pkg:/..."> e BrighterScript import
Contratos	Parâmetros de URL, tipos de requisição, tipos de resposta de handlers de rota
Monorepos	pnpm, npm, yarn workspaces + workspaces de linguagem mista (ex.: Next.js + Laravel, SwiftUI + Vapor, Roku multicanal sob src/apps/<creator>/)
Linguagens	TypeScript, JavaScript, Python, Go, Ruby, Elixir, Java, Kotlin, Rust, PHP, Dart, Swift, C#, BrightScript/BrighterScript

Geração de Configuração de IA

npx codesight --init

Gera arquivos de instrução prontos para uso para cada ferramenta de codificação de IA importante de uma só vez:

Arquivo	Ferramenta
CLAUDE.md	Claude Code
.cursorrules	Cursor
.github/copilot-instructions.md	GitHub Copilot
codex.md	OpenAI Codex CLI
AGENTS.md	OpenAI Codex agents
Each file is pre-filled with your project's stack, architecture, high-impact files, and required env vars. Your AI reads it on startup and
starts with full context from the first message.

MCP Server (14 Tools)

npx codesight --mcp

Runs as a Model Context Protocol server. Claude Code and Cursor call it directly to get project context on demand.

{
  "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

Codex timeout note: npx has to resolve the package on first run which can exceed the default 30-second timeout. Set startup_timeout_sec = 60 or install globally (npm install -g codesight) and use command = "codesight" instead — global installs start significantly faster.

Tool	What it does
codesight_get_wiki_index	Wiki catalog (~200 tokens) — read at session start
codesight_get_wiki_article	Read one wiki article by name: auth, database, payments, etc.
codesight_lint_wiki	Health check: orphan articles, missing cross-links
codesight_scan	Full project scan (~5K-5K tokens)
codesight_get_summary	Compact overview (~500 tokens)
codesight_get_routes	Routes filtered by prefix, tag, or method
codesight_get_schema	Schema filtered by model name
codesight_get_blast_radius	Impact analysis before changing a file
codesight_get_env	Environment variables (filter: required only)
codesight_get_hot_files	Most imported files with configurable limit
codesight_get_events	Background events: BullMQ queues, Celery tasks, Kafka topics, Redis pub/sub, EventEmitter
codesight_get_coverage	Test coverage map: which routes and models have test files
codesight_get_knowledge	Knowledge map from --mode knowledge: decisions, open questions, themes, note index
codesight_refresh	Force re-scan (results are cached per session)

Your AI asks for exactly what it needs instead of loading the entire context map. Session caching means the first call scans, subsequent calls return instantly.

AI Tool Profiles

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

Generates an optimized config file for a specific AI tool. Each profile includes your project summary, stack info, high-impact files, required env vars, and tool-specific instructions on how to use codesight outputs. For Claude Code, this includes MCP tool usage instructions. For Cursor, it points to the right codesight files. Each profile writes to the correct file for that tool.

Visual Report

npx codesight --open

Opens an interactive HTML dashboard in your browser. Routes table with method badges and tags. Schema cards with fields and relations. Dependency hot files with impact bars. Env var audit. Token savings breakdown. Useful for onboarding or just seeing your project from above.

GitHub Action

Add to your CI pipeline to keep context fresh on every 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/

Watch Mode and Git Hook

Watch mode re-scans automatically when your code changes:

npx codesight --watch

Only triggers on source and config files (.ts, .js, .py, .go, .prisma, .env, etc.). Ignores node_modules, build output, and non-code files. Shows which files changed before each re-scan. Your config (disabled detectors, plugins) is preserved across re-scans.

Git hook regenerates context on every commit:

npx codesight --hook

Context stays fresh without thinking about it.

All Options

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

How It Compares

	codesight	File concatenation tools	AST-based tools (e.g. code-review-graph)
Parsing	AST (TypeScript compiler) + regex fallback	None	Tree-sitter + SQLite
Token reduction	7x-12x base scan; 60-131x with targeted wiki queries	1x (dumps everything)	8x reported
Route detection	30+ frameworks, auto-detected	None	Limited
Schema parsing	14 ORMs with field types and relations	None	Varies
Blast radius	BFS through import graph	None	Yes
AI tool profiles	5 tools (Claude, Cursor, Codex, Copilot, Windsurf)	None	Auto-detect
MCP tools	14 specialized tools with session caching	None	22 tools
Setup	npx codesight (zero deps, zero config)	Copy/paste	pip install + optional deps
Dependencies	Zero (borrows TS from your project)	Varies	Tree-sitter, SQLite, NetworkX, etc.
Language	TypeScript (zero runtime deps)	Varies	Python
Scan time	185-290ms (small), 0.9-2.8s (10K files)	Varies	Under 2s reported

codesight is purpose-built for the problem most developers actually have: giving their AI assistant enough context to be useful without wasting tokens on file exploration. It focuses on structured extraction (routes, schema, components, dependencies) rather than general-purpose code graph analysis.

Contributing

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

PRs welcome. Open an issue first for large changes.

License

MIT

---