codeindex

Um mecanismo de inteligência estrutural 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 │  socket    │ codeindex daemon │
 │ (Claude,    │ 16 tools,       │  (relay)  │ ◄────────► │  one per         │
 │  Cursor…)   │ JSON-RPC        └───────────┘            │  workspace       │
 └─────────────┘                                          └────────┬─────────┘
 ┌─────────────┐   MCP (stdio)   ┌───────────┐                     │
 │  AI Agent   │ ◄─────────────► │ codeindex │ ◄───────────────────┘
 │  (session 2)│                 │  (relay)  │   tree-sitter parse (40+ langs)
 └─────────────┘                 └───────────┘   trigram + word index
                                                 dependency graph
                                                 one file watcher
                                                 snapshot persistence

Cada sessão em um repositório fala MCP stdio simples, como antes. Por trás disso, elas compartilham um único índice: a árvore é analisada uma vez, observada uma vez e gravada uma vez, não importa quantos agentes estejam conectados. Oito sessões em um repositório costumavam ser oito cópias do mesmo índice, oito observadores de arquivos e oito gravadores do mesmo snapshot; medido em um projeto de 720 arquivos, cada sessão passou de 87 MB para 7 MB, contra um daemon compartilhado de 77 MB.

Por quê

Agentes de codificação de IA gastam tokens lendo arquivos inteiros. O codeindex responde a perguntas estruturais — contornos de símbolos, definições, chamadores, raio de impacto, cadeias de dependências — 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 deus / núcleo estável / ilha / driver), literais codificados para verificar e o raio de impacto transitório 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ê quer também a skill e o hook:

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

# 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 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, both
# routing hooks 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 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, o workspace indexado e se um watcher está ativo
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 palavra/identificador no índice invertido de palavras
find_callers	Pontos de chamada de um símbolo, cada um com a função que o contém. Corresponde por nome, então uma definição com o mesmo nome em outro lugar é incluída
get_outline	Contorno estrutural de um arquivo (símbolos, contagens de linhas)
get_tree	Árvore de diretórios com metadados de arquivo
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 transitório: 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 do 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 22 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	Símbolos que nada nomeia fora de sua própria definição, separados da API pública não utilizada de um pacote de biblioteca
unwrap_audit	Locais de .unwrap() / expect / panic! (Rust), classificados por se um manipulador de requisição, um loop ou main os alcança
test_coverage	Arquivos sem cobertura de testes
architecture	Problemas arquiteturais — módulos deus, dependências circulares, ilhas
crossref	Referências de símbolos entre arquivos
type_drift	Incompatibilidades de assinaturas de tipos entre módulos
db_schema	Tabelas que as migrações criam e que nenhum código nomeia, e modelos ORM SQL que nenhuma migração cria
migration_parity	Migrações ausentes para mudanças 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
spawn_scan	Um interpretador iniciado em um loop ou timer, entre arquivos, classificado por custo de inicialização vezes taxa de spawn
deps	Inventário de dependências — versões duplicadas, crates não referenciados, crates de uso único
leak_shapes	Formas que um vazamento tem, cada uma emparelhada com a série de runtime que a decide
logic_shapes	Uma constante de bytes fixa contra o limite de memória da unidade que a implanta, e réplicas × tamanho do pool contra a capacidade de conexão de um pooler
call_cost	Loops sobre linhas classificados pelas idas e voltas de banco de dados e HTTP que cada elemento custa, contados pelo grafo de chamadas
field_contention	Um campo de estado declarado escrito por dois ou mais donos
health	Consolidação das análises acima em um único 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 --mcp --no-daemon              # ...without sharing the workspace daemon
codeindex --daemon-idle-secs 0           # Keep the daemon resident indefinitely
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

Fazendo com que seja usado

Um servidor que registra sem dizer a um agente quando recorrer a ele fica ocioso, e um índice ocioso não economiza nada, por mais baratas que sejam suas chamadas. O plugin entrega três coisas para isso, na ordem em que agem:

1. Um resumo de SessionStart. Cerca de 240 tokens, uma vez por sessão, em um repositório que contém arquivos de código: o codeindex está ativo, e aqui está a ferramenta para cada tipo de pergunta de código. Ele chega antes de o agente escolher uma ferramenta, que é o único momento que pode mudar a primeira escolha.
2. Uma dica de PreToolUse. Dispara na 1ª, 8ª e 25ª pergunta de código de uma sessão, quando uma varredura está prestes a responder algo que o índice responde melhor, e nomeia a ferramenta para aquela pergunta exata. Ela corresponde a Bash bem como a Read/Grep/Glob, porque um modo de permissão que roteia trabalho de arquivos pelo shell é onde a maioria das varreduras realmente acontece.
3. A skill, que o modelo carrega quando decide que a tarefa exige isso.

Conselhos perdem para o hábito, então o caso restrito em que o índice é estritamente melhor é recusado em vez de discutido: uma busca de identificador que é a linha de comando inteira, em um projeto que já foi indexado antes. Ele nunca recusa uma leitura de arquivo — os bytes são necessários antes de um Edit — nunca recusa uma linha que também compila ou testa, e para de recusar após três vezes em uma sessão, então nunca pode ser o motivo de uma sessão não prosseguir.

Isso está ativo por padrão, e é um único interruptor para desligar — nenhum arquivo para editar manualmente. É uma opção de plugin, então /plugin mostra como "Recusar uma varredura que o índice responde melhor" e o Claude Code passa sua resposta para o hook. Fora do plugin, ou para uma única sessão, CODEINDEX_ENFORCE=0 no ambiente substitui a opção e CODEINDEX_ENFORCE=1 a restaura.

Meça o efeito em vez de assumi-lo: python3 plugin/measure_routing.py conta, por sessão, quantas perguntas de código foram para uma varredura e quantas foram para o índice, em todos os homes do Claude Code na máquina.

Qual árvore é indexada

No modo --mcp, o diretório de trabalho pertence ao cliente, não a você, e frequentemente não é seu projeto: o Claude Code inicia o servidor MCP de um plugin a partir do diretório do próprio plugin e um servidor de escopo de usuário a partir de seu diretório de configuração. Então o workspace é resolvido nesta ordem, e a primeira resposta utilizável vence:

1. --workspace ou CODEINDEX_WORKSPACE. Uma resposta explícita nunca é substituída.
2. CLAUDE_PROJECT_DIR, que o Claude Code define em todo servidor MCP que ele inicia.
3. O diretório de lançamento, subindo em busca de um marcador .git, package.json, Cargo.toml, go.mod, build.zig ou pyproject.toml.
4. Os roots MCP do cliente. O servidor os solicita no handshake sempre que a raiz acima foi um palpite, e adota um quando o palpite foi recusado ou cai fora de toda raiz que o cliente relata. notifications/roots/list_changed também é respeitado, então um diretório adicionado com --add-dir ainda pode resgatar uma sessão.

status relata a raiz efetiva como workspace, e se um observador de arquivos está em execução como watcher. Verifique-os quando um resultado parecer vazio: um índice da árvore errada responde a cada pergunta com a mesma confiança que o certo.

Ele se recusa a indexar todo o seu diretório home, a raiz do sistema de arquivos ou uma pasta que apenas contém vários repositórios independentes. Um workspace recusado responde a cada consulta com o motivo e a única chamada que o corrige — index_workspace com o caminho do projeto — em vez de "sem resultados".

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 mudanças 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 relata qual backend está ativo como watcher_backend.
• Snapshot: persiste o índice completo em .codeindex.json, então uma reinicialização carrega o snapshot em vez de reindexar
• Servidor MCP: JSON-RPC sobre stdio, implementa o protocolo MCP 2024-11-05
• Daemon de workspace: a primeira sessão em um repositório inicia um daemon em segundo plano e se torna um relé para ele; sessões posteriores apenas se conectam. Um socket de domínio Unix no Linux, macOS e Windows 10 1803+, em $XDG_RUNTIME_DIR/codeindex (ou um diretório por usuário sob TMPDIR), nomeado por um hash do workspace e da versão do binário — então um binário recompilado nunca herda o daemon da versão anterior. Ele sai após 15 minutos sem nenhuma sessão conectada. Qualquer coisa que der errado cai para indexação em processo, que é o que acontecia antes de o daemon existir. Desligue-o com --no-daemon.

Suporte de plataforma

Cada linha é construída por CI e seus testes são executados nessa plataforma, exceto onde indicado. status relata o backend do observador ao vivo para que nunca seja um palpite.

	binário	testes executados em 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 launcher do plugin são scripts de shell, então eles
precisam de Git Bash, MSYS2 ou Cygwin — eles detectam isso e resolvem o asset .exe
correto. O plugin registra seu servidor por meio desse launcher, então um
Claude Code nativo do Windows sem um 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 baixado com curl é executado sem um aviso do Gatekeeper; um baixado por meio de um navegador fica 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 as fontes C do tree-sitter vinculadas corrompem por meio de seus caminhos de printf de depuração. Compilar o binário de teste e executá-lo diretamente são os mesmos testes sem esse protocolo no caminho.

Como ele se compara

	codeindex	ast-grep	ctags	LSIF	Sourcegraph
Nativo para MCP	Sim	Não	Não	Não	Não
Eficiente em tokens	Sim (esboços, 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, Antigravity e Cursor em um histórico pesquisável e expõe isso também via MCP.

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

Licença

MIT. Veja LICENSE.