polycodegraph

polycodegraph

Analise qualquer repositório em um grafo de código consultável. Rastreie um parâmetro de um fetch de frontend por todas as camadas até a consulta SQL. Alimenta Claude Code, Cursor e Windsurf via MCP — para que seu assistente de IA leia contexto focado em vez do codebase inteiro.

Mesmo Claude Sonnet 4.6. Mesmas 10 perguntas sobre dois repositórios reais (o próprio codegraph + FastAPI). Apenas o servidor MCP registrado muda. Reproduza com codegraph bench agent, dados brutos em bench/RESULTS_AGENT_LATEST.md.

Início rápido

pip install polycodegraph     # the PyPI distribution name
codegraph init                # the CLI binary + Python module + MCP server are all `codegraph` (see footnote ↓)
codegraph build               # parse repo → .codegraph/graph.db
codegraph serve               # web dashboard at http://127.0.0.1:8765

É isso. Três comandos e você tem um grafo consultável, um dashboard 3D e um servidor MCP com o qual sua IDE pode conversar.

Linguagens + frameworks (hoje)

Adicionar uma nova linguagem é um único módulo de parser tree-sitter + arquivo de fixture (~3 horas — veja codegraph/parsers/go.py para o template v1). PRs são bem-vindos.

O DIFERENCIAL — um grafo, tudo em cima

polycodegraph tem exatamente uma opinião: construa o grafo certo, e todo recurso interessante surge de graça.

As entradas que alimentam o grafo vão além de imports e arestas de chamada. polycodegraph lê parses tree-sitter para Python, TypeScript, JavaScript e Go; captura os argumentos de cada call-site como texto; reconhece 24 decorators de frameworks para que handlers FastAPI / Flask / Celery / pytest / Click / MCP / Django / SQLAlchemy nunca sejam confundidos com código morto; detecta rotas (@app.get("/x")) e fetches de frontend (fetch, axios, useSWR, useQuery); e costura URLs através da stack (/{id} ↔ ${id} ↔ :id) para rastrear um fetch até seu handler.

As saídas que vêm de graça quando o grafo está certo:

Código morto ciente de decorators, classificação de papéis (HANDLER / SERVICE / COMPONENT / REPO), raio de impacto, ciclos, detecção de funções sem teste, um rastreio cross-stack de ponta a ponta com anotações de renomeação, um dashboard 3D em modo foco, um modal de ciclo de vida no Learn Mode, embeddings locais para busca semântica + híbrida, um servidor MCP com 18 ferramentas e um CI de revisão de PR que faz diff do grafo da branch contra main.

Um único arquivo SQLite. Sem daemon. Sem rede. Viaja com sua branch git.

Como funciona

  ┌─────────────────────────────────────────────────────┐
  │  tree-sitter parsing                                │
  │  (Python, TS/JS, TSX, JSX, Go)                      │
  └─────────────────────────────────────────────────────┘
                        ↓
  ┌─────────────────────────────────────────────────────┐
  │  Cross-file resolution (R1, R2, R3)                 │
  │  ✓ per-name imports  ✓ relative imports             │
  │  ✓ constructor calls ✓ decorators                   │
  │  ✓ self.X.Y chains  ✓ fresh instances               │
  └─────────────────────────────────────────────────────┘
                        ↓
  ┌─────────────────────────────────────────────────────┐
  │  SQLite graph (nodes + edges)                       │
  │  DF0: call-site arguments                           │
  │  DF1: routes (FastAPI, Flask, aiohttp)              │
  │  DF2: fetches (fetch, axios, SWR, useQuery)         │
  │  DF3: URL stitching (/{id} ↔ ${id} ↔ :id)          │
  │  DF4: end-to-end trace (fetch→handler→service→DB)   │
  └─────────────────────────────────────────────────────┘
                   ↙            ↓            ↘
            CLI tools       Web dashboard      MCP server
         (graph, roles,    (3D focus view,  (18 tools for
         cycles, dead      architecture,     Claude Code,
         code, untested)   learn mode)       Cursor, etc.)

O que você pode fazer

Screenshot	Caso de uso
	Visualização 3D em foco — Escolha qualquer função, rastreie sua árvore de chamadas downstream real, expanda ou recolha ancestrais e descendentes inline. Mostrado: build_dashboard_payload com seus 15 callees diretos — find_dead_code, find_cycles, build_hld, find_hotspots, compute_metrics e o restante da stack de análise.
	Mapa de arquitetura — Handlers agrupados por papel (HANDLER, SERVICE, COMPONENT, REPO), componentes de infraestrutura (DB, cache, fila) e suas conexões de relance. Clique em um handler → Learn Mode abre um modal de ciclo de vida da requisição: TCP → TLS → HTTP → query → resposta.
	Rastreio cross-stack DF4 — Clique em qualquer handler na visualização de Arquitetura e o Learn Mode anima o ciclo de vida completo da requisição: DNS → TCP → TLS → HTTP → middleware → handler → service → SQL → 200 OK. O parâmetro user_id é destacado em cada salto com anotações de renomeação (userId → user_id → id). Uma consulta ao grafo, sem mergulhar em logs.
	Ferramentas MCP que seu assistente de IA chama diretamente — Uma resposta real de find_symbol("get_user") do servidor MCP do polycodegraph. Três resultados em ~50 tokens, classificados por papel como HANDLER vs SERVICE, sem necessidade de leitura de arquivos. Coloque isso junto com o grep do Claude Code e o assistente para de despejar arquivos inteiros na janela de contexto — veja o benchmark abaixo.

Benchmark — mesmo Claude, variando o grafo MCP

Quatro configurações. Mesmo Claude Sonnet 4.6. Mesmas 10 perguntas em dois codebases reais (o próprio polycodegraph + FastAPI). Todas as quatro configurações incluem as ferramentas nativas de grep + leitura de arquivos do Claude — o que todo dev recebe pronto no Claude Code ou Cursor. A única coisa que muda é se um grafo MCP também está registrado junto.

codegraph-self

fastapi

A leitura honesta nos dois repositórios:

• claude+grep sozinho é o mais correto (8/10) — Claude consegue responder à maioria das perguntas sobre o codebase com grep e leitura de arquivos inteiros. Mas paga o preço: 336k tokens, $1.17, 78s de latência média.
• + polycodegraph iguala isso dentro de uma pergunta (7/10) com custo 3× menor e latência 4× menor (90k tokens, $0.37, 20s). Porque polycodegraph retorna subgrafos pequenos e focados (~20-50 tokens por chamada) em vez de despejar arquivos inteiros via grep no contexto do Claude.
• Os outros grafos MCP são estritamente piores do que apenas usar grep. code-review-graph: 3/10 a $0.68. graphify: 5/10 a $0.50. Eles adicionam overhead de ferramentas sem compensar em corretude.

Reproduza: codegraph bench agent --only claude+grep,claude+grep+polycodegraph,claude+grep+code-review-graph,claude+grep+graphify. JSONL bruto por execução em bench/agent_raw_latest.jsonl. Metodologia completa em bench/README.md.

Instalação e uso

Via PyPI

pip install polycodegraph
codegraph init
codegraph build

Registre como servidor MCP

codegraph init escreve um .mcp.json no nível do projeto no repositório — Claude Code e Cursor detectam isso automaticamente assim que você abre o projeto. Para outros clientes, você precisa adicionar o servidor à configuração global manualmente por enquanto (v0.2 fará isso por você).

// Claude Code (global)  →  ~/.claude.json
// Cursor (global)       →  ~/.cursor/mcp.json   (or .cursor/mcp.json per workspace)
// Windsurf              →  ~/.windsurf/mcp.json
// OpenAI Codex CLI      →  ~/.codex/mcp.json
// GitHub Copilot CLI    →  ~/.config/copilot/mcp.json
// Zed                   →  ~/.config/zed/settings.json under "context_servers"
// Continue              →  ~/.continue/config.json under "experimental.modelContextProtocolServers"

{
  "mcpServers": {
    "codegraph": {
      "command": "codegraph",
      "args": ["mcp", "serve"]
    }
  }
}

O mesmo trecho JSON de cinco linhas funciona para todos os clientes — apenas o caminho do arquivo muda.

Depois, faça perguntas ao seu assistente como:

"Quais nós HANDLER não têm cobertura de teste?" "Mostre-me todos os chamadores de UserService.login com seus argumentos." "Rastreie GET /api/users/{id} do fetch de frontend até o banco de dados." "Qual é o raio de impacto de mudar esta função?"

Todas as 18 ferramentas retornam subgrafos pequenos e focados — sem inundar a janela de contexto.

Opcional: embeddings locais

pip install 'polycodegraph[embed]'
codegraph embed     # chunks the repo, embeds with nomic-ai/CodeRankEmbed

Desbloqueia as ferramentas MCP semantic_search e hybrid_search. Download do modelo de ~140 MB, roda localmente, sem chaves de API.

Demonstração ao vivo

Uma fixture pequena de FastAPI + SQLAlchemy + React está em examples/cross-stack-demo/. Rode polycodegraph nela para ver DF0, DF1, DF1.5, DF2, DF3 e DF4 todos ativados:

codegraph build --no-incremental --root examples/cross-stack-demo
codegraph dataflow trace "GET /api/users/{user_id}"

Veja o README da demo para a saída esperada.

Limitações (lista honesta)

O que polycodegraph ainda não faz. Listado aqui para que as afirmações do benchmark e do README permaneçam limpas.

• Inferência de tipos (Mypy / Pyright). DF0 captura o texto dos argumentos, não os tipos. Roadmap v0.3.
• Identidade de valor de argumento entre saltos. DF4 emite saltos ordenados com anotações de renomeação; a propagação completa de valor único do corpo do fetch → parâmetro de rota → argumento de service → coluna do banco é adiada (v0.3).
• Docstrings são armazenadas em cada nó, mas ainda não são consumidas pela análise. Embeddings as usam como texto de corpo alternativo; código morto, classificação de papéis e dataflow as ignoram. Roadmap v0.3.
• Mineração de histórico Git (semântica de mensagens de commit, sinais de autor / frequência de alteração). Não implementado. Git é usado apenas para o SHA do HEAD atual e o diff de revisão de PR. Roadmap v0.4.
• Paridade de resolver por linguagem (v0.1.2). Python entrega as correções completas R1/R2/R3. Padrões R2 do TypeScript (aliases de caminho, binding de instância nova, arestas de chamada de decorator) são adiados.
• Símbolos CLI do Typer não são marcados como HANDLER (v0.1.x). DF1.5 só classifica decorators de frameworks HTTP.
• Visualização de async / await (v0.4). DF4 percorre apenas o grafo de chamadas síncrono.
• Renderização de ramos de caminho de erro (v0.4). Learn Mode mostra o caminho feliz.
• Middleware de autenticação como fase distinta (v0.4). Hoje a autenticação aparece como um nó CALL comum.
• Destaque simultâneo de múltiplos parâmetros (v0.4). Apenas seleção de parâmetro único.
• Rastreios entre processos (v0.4). Ainda não é possível vincular múltiplos arquivos .codegraph/graph.db.

Roadmap

Sobre o auto-grafo: de 451 achados de código morto a 0

Rodamos polycodegraph no próprio código-fonte como alvo de regressão. Os achados de código morto caíram de 451 → 24+ → 15 → 0 conforme o resolver foi endurecido, a detecção de pontos de entrada ciente de decorators foi implementada e métodos intencionais de API pública foram marcados com # pragma: codegraph-public-api.

Estatísticas atuais do auto-grafo:

• 3,320 nós (arquivos, classes, funções, imports)
• 7,557 arestas (5,245 CALLS, 1,357 DEFINED_IN, 886 IMPORTS, 28 INHERITS, 12 ROUTE, 27 FETCH_CALL, 1 READS_FROM, 1 WRITES_TO)
• 3 ciclos, todos documentados e aceitos (redesenho do dashboard, auto-recursão do parser, falso positivo do resolver MCP serve/run)
• 0 achados de código morto (com isenções de pragma para métodos de API pública)
• 637 testes passando (537 pytest Python + 100 testes Node)

Onde se encaixa

A diferença não é um algoritmo de grafo mais sofisticado — é que o polycodegraph trata rastrear este argumento através da stack como uma operação de primeira classe, não um grep complementar. Ferramentas de recuperação baseadas em embeddings (code-review-graph, Cursor, Cody) lidam bem com prosa / docstrings; a arquitetura correta é grafo + embeddings no mesmo loop MCP, e a v0.1.0 entrega ambos.

# Graph building
codegraph init      # interactive setup: detect languages, configure ignore globs, register MCP
codegraph build     # parse repo with tree-sitter, write/update .codegraph/graph.db
codegraph status    # graph freshness, last build time, drift indicators

# Analysis
codegraph analyze                # whole-project audit: dead code, cycles, untested, hotspots, metrics
codegraph query callers <symbol> # reverse-BFS: who calls this?
codegraph query callees <symbol> # forward traversal: what does this call?
codegraph query subgraph <symbol>
codegraph query deadcode
codegraph query untested
codegraph query cycles
codegraph query hotspots
codegraph query metrics

# Visualization
codegraph serve                       # web dashboard at http://127.0.0.1:8765
codegraph viz                         # Mermaid / interactive HTML / SVG
codegraph explore                     # static subgraph explorer pages (good for sharing)
codegraph dataflow trace "<M> <path>" # walk DF1→DF4 to trace endpoint frontend→DB

# PR review + baselines
codegraph review              # graph-diff current branch vs baseline; CSV or Markdown
codegraph baseline save       # snapshot current graph as the local baseline
codegraph baseline status
codegraph baseline push       # optional S3 remote
codegraph hook install        # pre-push git hook running codegraph review
codegraph hook uninstall

# MCP + embeddings
codegraph mcp serve           # MCP stdio server: 18 tools for Claude Code / Cursor / Windsurf
codegraph embed               # chunk + embed (nomic-ai/CodeRankEmbed); enables semantic + hybrid search

# Cross-repo workspace mode
codegraph workspace init      # ~/.codegraph/workspace.yml
codegraph workspace add <path>
codegraph workspace remove <path>
codegraph workspace list
codegraph workspace status
codegraph workspace sync [--only <name>]

gh auth refresh -h github.com -s workflow
cp .github/ci-templates/pr-review.workflow.yml .github/workflows/pr-review.yml
git add .github/workflows/pr-review.yml
git commit -m "ci: activate codegraph PR review"
git push

./scripts/test-pr-review-locally.sh

Desenvolvimento

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

ruff check .                    # lint
mypy --strict codegraph         # type-check
pytest -q                       # 537 Python tests
node --test tests/*.js          # 100 Node tests
./scripts/test-pr-review-locally.sh  # dry-run the PR review workflow

As verificações de CI estão definidas em .github/workflows/ci.yml. Novo no repositório? Comece por docs/GETTING_STARTED.md. Para convenções de commit e processo de PR, veja CONTRIBUTING.md.

Uma nota sobre os nomes

Este projeto é instalado a partir do PyPI como polycodegraph porque o nome simples codegraph já estava ocupado quando a v0.1.0 foi lançada. Todo o resto — o pacote Python que você importa, o binário da CLI que você executa e a chave do servidor MCP que você registra — é codegraph, o nome original do projeto. Planejamos unificar em polycodegraph em todos os lugares na v0.2 (renomeação da CLI com um alias codegraph por uma release). Por enquanto: dois nomes, uma ferramenta.

Agradecimentos

O polycodegraph se apoia em tree-sitter (parsing), vasturiano/3d-force-graph (renderização 3D), networkx (algoritmos de grafo), pydantic (schema tipado), typer (CLI), rich (saída de console), nomic-ai/CodeRankEmbed (embeddings), e o Model Context Protocol Python SDK.

Licença

MIT © mochan

Suporte comercial, implantações e forks com licença personalizada disponíveis — contato smochan07@gmail.com. O polycodegraph em si é e permanece MIT; a linha de contato existe para equipes que desejam suporte empresarial ou acordos de licença específicos por cima.

Pull requests são bem-vindos. Veja CONTRIBUTING.md para configuração local, verificações de CI, convenções de commit e o Contributor License Agreement com um clique que você será solicitado a assinar no seu primeiro PR.