codeix

codeix

codeix.dev · Busca semântica rápida de código para agentes de IA — encontre símbolos, referências e chamadores em qualquer base de código.

codeix                 # start MCP server, watch for changes
codeix build           # parse source files, write .codeindex
codeix -r ~/project build  # build from a specific directory

Por quê

Agentes de codificação de IA gastam a maior parte do orçamento de tokens encontrando código antes de poderem trabalhar nele. Eles fazem grep, leem arquivos, fazem grep novamente, voltam atrás. Em uma base de código grande, o agente pode queimar milhares de tokens apenas para localizar a função certa — ou, pior, não encontrá-la e alucinar.

O codeix dá ao agente um mapa pré-construído da sua base de código. Uma única consulta estruturada retorna o nome do símbolo, arquivo, intervalo de linhas, assinatura e pai — sem varredura, sem adivinhação.

O que as ferramentas existentes fazem de errado

Problema	O que acontece hoje
Sem estrutura	grep encontra correspondências de texto, não símbolos. O agente não consegue distinguir uma definição de função de um comentário que a menciona.
Re-análise lenta	Indexadores baseados em Python re-analisam tudo na inicialização. Em bases de código grandes, você espera.
Não compartilhável	Índices são caches locais — efêmeros, por máquina. Um novo desenvolvedor ou runner de CI começa do zero.
Sem composição	Monorepo com 10 pacotes? Dependências com APIs úteis? Não há como consultar além dos limites.
Prosa é invisível	TODOs, docstrings, mensagens de erro — pesquisáveis por grep, mas não seletivamente. Você não pode pesquisar apenas comentários sem também corresponder ao código.

O que o codeix faz de diferente

• Commitado no git — o índice é um diretório .codeindex que você commita junto com seu código. Clone o repositório, o índice já está lá. Sem re-indexação.
• Compartilhável — autores de bibliotecas podem enviar .codeindex em seus pacotes npm/PyPI/crates.io. Consumidores obtêm navegação instantânea das dependências.
• Componível — o servidor MCP descobre automaticamente os índices de dependências e os monta. Consulte seu código e suas dependências em um só lugar.
• Estruturado para LLMs — símbolos têm tipos, assinaturas, relações de pai e intervalos de linhas. O agente obtém exatamente o que precisa em uma única chamada de ferramenta, em vez de montar tudo a partir de texto bruto.
• Busca em prosa — search --scope text tem como alvo comentários, docstrings e literais de string especificamente. Encontre TODOs, encontre a mensagem de erro que um usuário relatou, encontre o que a docstring de uma função diz — sem ruído do código.
• Rápido — compila em segundos, consultas em milissegundos. Rust + tree-sitter + SQLite FTS5 em memória por baixo dos panos.

O formato .codeindex

Um formato aberto e portátil para indexação estruturada de código. Arquivos JSONL simples que você commita junto com seu código — diffs amigáveis ao git, legíveis por humanos com grep e jq, sem blobs binários.

.codeindex/
  index.json        # manifest: version, name, languages
  files.jsonl       # one line per source file (path, lang, hash, line count)
  symbols.jsonl     # one line per symbol (functions, classes, imports, with signatures)
  texts.jsonl       # one line per comment, docstring, string literal

Qualquer ferramenta que consiga analisar JSON pode consumir um .codeindex. O codeix o constrói usando tree-sitter, e agentes de IA o consultam por meio do MCP (Model Context Protocol).

Exemplo — symbols.jsonl:

{"file":"src/main.py","name":"os","kind":"import","line":[1,1]}
{"file":"src/main.py","name":"Config","kind":"class","line":[22,45]}
{"file":"src/main.py","name":"Config.__init__","kind":"method","line":[23,30],"parent":"Config","sig":"def __init__(self, path: str, debug: bool = False)"}
{"file":"src/main.py","name":"main","kind":"function","line":[48,60],"sig":"def main(args: list[str]) -> int"}

Envie seu índice junto com seu pacote

Inclua .codeindex no seu pacote e todo desenvolvedor que depende de você obtém navegação instantânea da sua API — sem configuração, sem re-indexação.

Funciona com repositórios Git, npm, PyPI e crates.io.

Ferramentas MCP

Sete ferramentas, zero configuração. O agente consulta imediatamente — sem init, sem config, sem refresh.

Ferramenta	O que faz
explore	Explore a estrutura do projeto: metadados, subprojetos, arquivos agrupados por diretório
search	Busca unificada de texto completo em símbolos, arquivos e textos (FTS5, ranqueado por BM25) com filtros de escopo/tipo/caminho/projeto
get_file_symbols	Lista todos os símbolos em um arquivo
get_children	Obtém os filhos de uma classe/módulo
get_callers	Encontra todos os lugares que chamam ou referenciam um símbolo
get_callees	Encontra todos os símbolos que uma função/método chama
flush_index	Grava alterações pendentes do índice no disco

Descoberta de projetos

Inicie o codeix a partir de qualquer diretório. Ele percorre para baixo e trata cada diretório que contém .git/ como um projeto separado — cada um recebe seu próprio .codeindex.

Funciona uniformemente para repositórios únicos, monorepos, repositórios irmãos e submódulos git. Sem necessidade de configuração.

Linguagens

Gramáticas tree-sitter, controladas por recursos em tempo de compilação:

Linguagem	Flag de recurso	Padrão	Extensões
Python	lang-python	yes	.py .pyi .pyw
Rust	lang-rust	yes	.rs
JavaScript	lang-javascript	yes	.js .mjs .cjs .jsx
TypeScript	lang-typescript	yes	.ts .mts .cts .tsx
Go	lang-go	yes	.go
Java	lang-java	yes	.java
C	lang-c	yes	.c .h
C++	lang-cpp	yes	.cpp .cc .cxx .hpp .hxx
Ruby	lang-ruby	yes	.rb .rake .gemspec
C#	lang-csharp	yes	.cs
Markdown	lang-markdown	yes	.md .markdown

Suporte a Markdown

Arquivos Markdown são analisados em busca de cabeçalhos (tanto estilo ATX # quanto sublinhado Setext), que são indexados como símbolos section com relações hierárquicas de pai-filho — permitindo extração de TOC e navegação pela estrutura do documento.

Blocos de código cercados são extraídos como entradas de texto code, vinculados à seção que os contém.

Scripts embutidos

Arquivos HTML, Vue, Svelte e Astro são pré-processados para extrair blocos <script> embutidos, que são então analisados com a gramática de JavaScript ou TypeScript:

Formato	Extensões	Detecção de script
HTML	.html .htm	tags <script>, com lang="ts" opcional
Vue	.vue	<script> e <script setup>, com lang="ts" opcional
Svelte	.svelte	<script>, com lang="ts" opcional
Astro	.astro	frontmatter --- (sempre TypeScript) + tags <script> opcionais

Os números de linha no índice apontam para o arquivo original, não para o bloco de script extraído.

Instalação

# npm / npx — run without installing
npx codeix

# pip / uvx — run without installing
uvx codeix

# Rust
cargo install codeix

# Homebrew
brew install codeix

# Or build from source
git clone https://github.com/montanetech/codeix.git
cd codeix
cargo build --release

Todos os canais instalam o mesmo binário único. Sem dependências de runtime.

Uso

# Build the index for the current project
codeix build

# Build from a specific directory (discovers all git repos below)
codeix -r ~/projects build

# Start MCP server (default command, watches for changes)
codeix

# Or explicitly
codeix serve
codeix serve --no-watch

# Serve from a specific directory
codeix -r ~/projects serve

Configuração do cliente MCP

Adicione à configuração do seu cliente MCP (ex.: Claude Desktop, Cursor):

{
  "mcpServers": {
    "codeix": {
      "command": "codeix"
    }
  }
}

Princípios de design

• Somente local — sem rede, sem chaves de API, funciona offline e em ambientes isolados
• Determinístico — a mesma fonte sempre produz o mesmo índice (diffs limpos)
• Componível — índices de dependências são descobertos automaticamente e montados no momento da consulta
• Superfície mínima — 7 ferramentas de consulta, zero encanamento de gerenciamento

Arquitetura

Veja docs/architecture.md para o conjunto completo de registros de decisão de arquitetura.

Licença

MIT OR Apache-2.0