codeindex

Um mecanismo estrutural de inteligência de código que roda como um servidor MCP para agentes de codificação de IA.

Ele indexa seu código com tree-sitter (mais de 40 linguagens), constrói um índice de texto completo por trigramas, um índice invertido de palavras e um grafo de dependências — e os expõe por meio de 16 ferramentas MCP.

 ┌─────────────┐      MCP (stdio)       ┌──────────────┐
 │  AI Agent   │ ◄─────────────────────► │   codeindex  │
 │ (Claude,    │   16 tools, JSON-RPC    │  (Zig binary) │
 │  Cursor…)   │                         │              │
 └─────────────┘                         └──────┬───────┘
                                                │
                                   tree-sitter parse (40+ langs)
                                         trigram + word index
                                         dependency graph
                                         snapshot persistence

Por quê

Agentes de codificação de IA gastam tokens lendo arquivos inteiros. O codeindex responde perguntas estruturais — contornos de símbolos, definições, chamadores, raio de impacto, cadeias de dependência — em algumas centenas de tokens em vez de milhares.

Uma única chamada de plan_change retorna: onde um símbolo é definido, todos os pontos de chamada, o papel arquitetural do arquivo (módulo god / núcleo estável / ilha / driver), literais codificados para verificar e o raio de impacto transitivo completo se o arquivo mudar.

Início rápido

O caminho mais curto, se você tiver Node 18+. Nada mais para instalar, sem chave, sem configuração — o pacote é um wrapper de 4 KB que busca o binário para sua plataforma e o verifica contra as somas de verificação publicadas:

claude mcp add codeindex -- npx -y @munhq/codeindex

Sem Node, ou você também quer a skill e o hook:

# Prebuilt binary + skill + MCP registration, in one command
curl -fsSL https://raw.githubusercontent.com/munhq/codeindex/main/install.sh | bash

# Or build from source:
cd zig && ./fetch-vendor.sh && zig build -Doptimize=ReleaseFast

Docker, para hosts que instalam servidores MCP como imagens. O workspace é montado como somente leitura; o codeindex nunca grava nele:

docker run -i --rm -v "$PWD:/workspace:ro" munhq/codeindex

Registre com seu agente de IA:

# Claude Code — the plugin is the one-step path. It ships the skill, the hook
# and the MCP server together, and its launcher finds or fetches the binary.
claude plugin marketplace add munhq/codeindex
claude plugin install codeindex@codeindex

# Without the plugin (or for a different MCP client), register the binary
# directly. Do not do both: two registrations mean two servers, two copies of
# every tool schema, and two writers on one snapshot. install.sh detects the
# plugin and skips this step when it is present.
claude mcp add -s user codeindex -- ~/.local/bin/codeindex --mcp

# Cursor / Claude Desktop / other MCP clients: add to your config
{
  "mcpServers": {
    "codeindex": {
      "command": "npx",
      "args": ["-y", "@munhq/codeindex"]
    }
  }
}

Cada listagem aponta para o mesmo servidor: npm @munhq/codeindex, o registro oficial do MCP como io.github.munhq/codeindex e Smithery como munhq/codeindex.

Na próxima vez que seu agente iniciar, o codeindex indexa seu projeto em segundo plano e atende consultas estruturais.

Ferramentas MCP

Ferramenta	O que faz
status	Estatísticas do índice: contagem de arquivos, contagem de símbolos, estado da indexação, % de economia de tokens
search	Busca de texto completo acelerada por trigramas em todos os arquivos indexados
find_symbol	Encontra definições de símbolos (funções, structs, classes…) por nome
find_word	Consulta exata de palavras/identificadores no índice invertido de palavras
find_callers	Chamadores aproximados de um símbolo (heurística, sem resolução completa de nomes)
get_outline	Contorno estrutural de um arquivo (símbolos, contagens de linhas)
get_tree	Árvore de diretórios com metadados de arquivos
get_imports	Quais arquivos um determinado arquivo importa/depende
get_imported_by	Dependências reversas — quem importa este arquivo
get_change_impact	Raio de impacto transitivo: o que quebra se um arquivo mudar
plan_change	Plano completo de refatoração para um símbolo ou arquivo — definições, chamadores, papel do arquivo, literais, raio de impacto
get_hot_files	Arquivos alterados recentemente ordenados por recência
read_file	Lê o conteúdo de um arquivo com intervalo de linhas opcional
read_symbol	Lê apenas o código-fonte de um símbolo (com linhas de contexto opcionais)
index_workspace	Indexa ou reindexa um diretório de workspace
analyze	Executa uma das 16 análises de código (veja abaixo)

Análises (ferramenta analyze)

Análise	O que encontra
security	Segredos codificados, padrões de injeção de SQL, blocos inseguros, uso de eval
dead_code	Arquivos e símbolos não referenciados
unwrap_audit	Tratamento de erros propenso a .unwrap() / pânico (Rust)
test_coverage	Arquivos sem cobertura de testes
architecture	Problemas arquiteturais — módulos god, dependências circulares, ilhas
crossref	Referências de símbolos entre arquivos
type_drift	Incompatibilidades de assinaturas de tipos entre módulos
db_schema	Divergência de esquema de banco de dados entre migrações e código
migration_parity	Migrações ausentes para alterações de esquema
manifest_compliance	Problemas de conformidade em package.json / Cargo.toml / go.mod
literal_scan	URLs, IPs, portas, caminhos absolutos e TODOs codificados
coupling	Métricas de acoplamento de módulos
cycles	Detecção de dependências circulares
duplication	Funções livres reinventadas — o mesmo trabalho escrito duas vezes
clones	Corpos de funções copiados e colados, ignorando nomes e espaços em branco
health	Resumo das análises acima em um relatório de saúde do índice

Linguagens suportadas

Mais de 40 linguagens via tree-sitter: Rust, Python, TypeScript/TSX, Go, Zig, C, C++, Java, Ruby, Bash, C#, Kotlin, Lua, Scala, Elixir, R, Swift, Dart, Haskell, TOML, JSON, YAML, HTML, CSS, SCSS, SQL, HCL, Dockerfile, Markdown, Nix, Make e outras.

Configuração

codeindex --mcp                          # Run as MCP server (stdio)
codeindex --workspace ./my-project       # Index a specific directory
codeindex --project-id my-project        # Project identifier
codeindex -v                             # Print version
codeindex -h                             # Print help

# Environment variables
CODEINDEX_WORKSPACE=/path/to/project     # Same as --workspace
CODEINDEX_PROJECT_ID=my-project          # Same as --project-id

O codeindex detecta automaticamente a raiz do projeto subindo a partir do diretório de trabalho procurando por .git, package.json, Cargo.toml, go.mod, build.zig, pyproject.toml, etc.

Ele se recusa a indexar todo o seu diretório pessoal ou a raiz do sistema de arquivos — passe --workspace para ser explícito.

Arquitetura

• Parser: tree-sitter com mais de 40 gramáticas, compilado em um único binário
• Índice: índice de trigramas para busca de texto difusa + índice invertido de palavras para consulta exata de identificadores
• Grafo de dependências: resolução de importações em nível de arquivo com arestas diretas e reversas
• Armazenamento de versões: rastreia alterações de arquivos com números de sequência para atualizações incrementais
• Observador ao vivo: reindexa em criação/modificação/exclusão de arquivos (thread em segundo plano no modo MCP). inotify no Linux; uma varredura de polling no macOS e Windows, que compara mtime e tamanho a cada poucos segundos. status informa qual backend está ativo como watcher_backend.
• Snapshot: persiste o índice completo em .codeindex.json, para que uma reinicialização carregue o snapshot em vez de reindexar
• Servidor MCP: JSON-RPC sobre stdio, implementa o protocolo MCP 2024-11-05

Suporte de plataforma

Cada linha é construída pela CI e seus testes são executados nessa plataforma, exceto onde indicado. status informa o backend do observador ao vivo para que nunca seja uma suposição.

	binário	testes na CI	observador	install.sh	plugin
Linux x86_64	Sim	Sim	inotify	Sim	Sim
Linux aarch64	Sim	compilação cruzada	inotify	Sim	Sim
macOS aarch64	Sim	Sim	polling	Sim	Sim
macOS x86_64	Sim	compilação cruzada	polling	Sim	Sim
Windows x86_64	Sim	Sim	polling	precisa de um shell	veja abaixo
Windows aarch64	Sim	compilação cruzada	polling	precisa de um shell	veja abaixo

No Windows, install.sh e o lançador do plugin são scripts de shell, então eles precisam de Git Bash, MSYS2 ou Cygwin — eles detectam isso e resolvem o ativo .exe correto. O plugin registra seu servidor por meio desse lançador, então um Claude Code nativo do Windows sem shell deve registrar o binário diretamente:

claude mcp add -s user codeindex -- C:\path\to\codeindex.exe --mcp

Nada aqui é assinado ou notarizado. No macOS, um binário obtido com curl é executado sem um prompt do Gatekeeper; um baixado por navegador é colocado em quarentena, e xattr -d com.apple.quarantine codeindex o limpa.

Compilando a partir do código-fonte

Requer Zig 0.16.0.

cd zig
./fetch-vendor.sh    # Clone tree-sitter + 40 grammar repos
zig build -Doptimize=ReleaseFast
# Binary: zig/zig-out/bin/codeindex

Execute os testes:

cd zig && zig build test-bin && ./zig-out/bin/test

zig build test roteia os resultados pelo protocolo IPC do build runner na saída padrão, que os fontes C do tree-sitter vinculados corrompem por meio de seus caminhos de depuração printf. Compilar o binário de teste e executá-lo diretamente são os mesmos testes sem esse protocolo no caminho.

Como se compara

	codeindex	ast-grep	ctags	LSIF	Sourcegraph
Nativo MCP	Sim	Não	Não	Não	Não
Eficiente em tokens	Sim (contornos, não arquivos completos)	Não	Parcial	Sim	Sim
Binário único	Sim	Sim	Sim	Não	Não (servidor)
Observador ao vivo	Sim (inotify / polling)	Não	Não	Não	Não
Grafo de dependências	Sim	Não	Não	Sim	Sim
Raio de impacto	Sim (transitivo)	Não	Não	Não	Parcial
Planejador de refatoração	Sim (plan_change)	Não	Não	Não	Não
Linguagens	40+	20+	50+	Varia	Varia

Combina com chat-recall

O codeindex responde perguntas sobre o código à sua frente. chat-recall responde perguntas sobre o trabalho que você já fez — ele indexa suas sessões do Claude Code, Gemini CLI, Codex, OpenCode e Antigravity em um histórico pesquisável e o expõe também via MCP.

Juntos, eles cobrem as duas metades do que um agente esquece: o codeindex impede que ele releia arquivos que poderia ter contornado, e o chat-recall impede que ele refaça trabalho que já concluiu. O chat-recall detecta um binário codeindex no seu PATH e registra quatro ferramentas extras de inteligência de código quando encontra um — nenhum requer o outro.

Licença

MIT. Veja LICENSE.