Autodev Codebase

@autodev/codebase

Uma ferramenta de busca semântica de código baseada em embeddings vetoriais com servidor MCP e integração multi-modelo. Pode ser usada como ferramenta CLI pura. Suporta Ollama para embedding e reordenação totalmente locais, permitindo operação offline completa e proteção de privacidade para seu repositório de código.

# Semantic code search - Find code by meaning, not just keywords
╭─ ~/workspace/autodev-codebase 
╰─❯ codebase search "user manage" --demo
Found 20 results in 5 files for: "user manage"

==================================================
File: "hello.js"
==================================================
< class UserManager > (L7-20)
class UserManager {
  constructor() {
    this.users = [];
  }

  addUser(user) {
    this.users.push(user);
    console.log('User added:', user.name);
  }

  getUsers() {
    return this.users;
  }
}
……

# Call graph analysis - Trace function call relationships and execution paths
╭─ ~/workspace/autodev-codebase 
╰─❯ codebase call --demo --query="app,addUser"
Connections between app, addUser:

Found 2 matching node(s):
  - demo/app:L1-29
  - demo/hello.UserManager.addUser:L12-15

Direct connections:
  - demo/app:L1-29 → demo/hello.UserManager.addUser:L12-15

Chains found:
  - demo/app:L1-29 → demo/hello.UserManager.addUser:L12-15

# Code outline with AI summaries - Understand code structure at a glance
╭─ ~/workspace/autodev-codebase 
╰─❯ codebase outline 'hello.js' --demo --summarize
# hello.js (23 lines)
└─ Defines a greeting function that logs a personalized hello message and returns a welcome string. Implements a UserManager class managing an array of users with methods to add users and retrieve the current user list. Exports both components for external use.

   2--5 | function greetUser
   └─ Implements user greeting logic by logging a personalized hello message and returning a welcome message

   7--20 | class UserManager
   └─ Manages user data with methods to add users to a list and retrieve all stored users

   12--15 | method addUser
   └─ Adds a user to the users array and logs a confirmation message with the user's name.

🚀 Recursos

• 🔍 Busca Semântica de Código: Busca baseada em vetores usando modelos avançados de embedding
• 🔗 Análise de Grafo de Chamadas: Rastreie relações de chamadas de funções e caminhos de execução
• 🌐 Servidor MCP: Servidor MCP baseado em HTTP com adaptadores SSE e stdio
• 💻 Ferramenta CLI Pura: Interface de linha de comando autônoma sem dependências de GUI
• ⚙️ Configuração em Camadas: Gerenciamento de configuração CLI, de projeto e global
• 🎯 Filtragem Avançada de Caminhos: Padrões glob com expansão de chaves e exclusões
• 🌲 Análise Tree-sitter: Suporte a mais de 40 linguagens de programação
• 💾 Integração Qdrant: Banco de dados vetorial de alto desempenho
• 🔄 Múltiplos Provedores: OpenAI, Ollama, Jina, Gemini, Mistral, OpenRouter, Vercel
• 📊 Monitoramento em Tempo Real: Atualizações automáticas de índice
• ⚡ Processamento em Lote: Processamento paralelo eficiente
• 📝 Extração de Esboço de Código: Gere esboços estruturados de código com resumos de IA
• 💨 Cache de Análise de Dependências: Cache inteligente para reanálise 10-50x mais rápida

📦 Instalação

1. Dependências

brew install ollama ripgrep
ollama serve
ollama pull nomic-embed-text

2. Qdrant

docker run -d -p 6333:6333 -p 6334:6334 --name qdrant qdrant/qdrant

3. Instalação

npm install -g @autodev/codebase
codebase config --set embedderProvider=ollama,embedderModelId=nomic-embed-text

🛠️ Início Rápido

# Demo mode (recommended for first-time)
# Creates a demo directory in current working directory for testing

# Index & search
codebase index --demo
codebase search "user greet" --demo

# Call graph analysis
codebase call --demo --query="app,addUser"

# MCP server
codebase index --serve --demo

📋 Comandos

📝 Esboços de Código

# Extract code structure (functions, classes, methods)
codebase outline "src/**/*.ts"

# Generate code structure with AI summaries
codebase outline "src/**/*.ts" --summarize

# View only file-level summaries
codebase outline "src/**/*.ts" --summarize --title

# Clear summary cache
codebase outline --clear-summarize-cache

🔗 Análise de Grafo de Chamadas

# 📊 Statistics Overview (no --query)
codebase call                           # Show statistics overview
codebase call --json                    # JSON format
codebase call src/commands              # Analyze specific directory

# 🔍 Function Query (with --query)
codebase call --query="getUser"         # Single function call tree (default depth: 3)
codebase call --query="main" --depth=5  # Custom depth
codebase call --query="getUser,validateUser"  # Multi-function connections (default depth: 10)

# 🎨 Visualization
codebase call --viz graph.json          # Export Cytoscape.js format
codebase call --open                    # Open interactive viewer
codebase call --viz graph.json --open   # Export and open

# Specify workspace (works for both modes)
codebase call --path=/my/project --query="main"

Padrões de Consulta:

• Correspondência exata: --query="functionName" ou --query="*ClassName.methodName"
• Curingas: * (quaisquer caracteres), ? (caractere único)
  • Exemplos: --query="get*", --query="*User*", --query="*.*.get*"
• Função única: --query="main" - Mostra a árvore de chamadas (ascendente + descendente)
  • Profundidade padrão: 3 (evita saída excessiva)
• Múltiplas funções: --query="main,helper" - Analisa caminhos de conexão entre funções
  • Profundidade padrão: 10 (busca mais profunda necessária para encontrar caminhos)

Linguagens Suportadas:

• TypeScript/JavaScript (.ts, .tsx, .js, .jsx)
• Python (.py)
• Java (.java)
• C/C++ (.c, .h, .cpp, .cc, .cxx, .hpp, .hxx, .c++)
• C# (.cs)
• Rust (.rs)
• Go (.go)

🔍 Indexação e Busca

# Index the codebase
codebase index --path=/my/project --force

# Search with filters
codebase search "error handling" --path-filters="src/**/*.ts"

# Search with custom limit and minimum score
codebase search "authentication" --limit=20 --min-score=0.7
codebase search "API" -l 30 -S 0.5

# Search in JSON format
codebase search "authentication" --json

# Clear index data
codebase index --clear-cache --path=/my/project

🌐 Servidor MCP

# HTTP mode (recommended)
codebase index --serve --port=3001 --path=/my/project

# Stdio adapter
codebase stdio --server-url=http://localhost:3001/mcp

⚙️ Configuração

# View config
codebase config --get
codebase config --get embedderProvider --json

# Set config
codebase config --set embedderProvider=ollama,embedderModelId=nomic-embed-text
codebase config --set --global qdrantUrl=http://localhost:6333

🚀 Recursos Avançados

🔍 Reordenação de Busca com LLM

Ative a reordenação com LLM para melhorar drasticamente a relevância da busca:

# Enable reranking with Ollama (recommended)
codebase config --set rerankerEnabled=true,rerankerProvider=ollama,rerankerOllamaModelId=qwen3-vl:4b-instruct

# Or use OpenAI-compatible providers
codebase config --set rerankerEnabled=true,rerankerProvider=openai-compatible,rerankerOpenAiCompatibleModelId=deepseek-chat

# Search with automatic reranking
codebase search "user authentication"  # Results are automatically reranked by LLM

Benefícios:

• 🎯 Maior precisão: O LLM entende a relevância semântica além da similaridade vetorial
• 📊 Pontuação inteligente: Os resultados são reordenados em uma escala de 0 a 10 com base na relevância da consulta
• ⚡ Processamento em lote: Lida eficientemente com grandes conjuntos de resultados com tamanhos de lote configuráveis
• 🎛️ Controle de limite: Filtre resultados com rerankerMinScore para manter apenas correspondências de alta qualidade

Filtragem de Caminhos e Exportação

# Path filtering with brace expansion and exclusions
codebase search "API" --path-filters="src/**/*.ts,lib/**/*.js"
codebase search "utils" --path-filters="{src,test}/**/*.ts"

# Export results in JSON format for scripts
codebase search "auth" --json

Filtragem de Caminhos e Exportação

# Path filtering with brace expansion and exclusions
codebase search "API" --path-filters="src/**/*.ts,lib/**/*.js"
codebase search "utils" --path-filters="{src,test}/**/*.ts"

# Export results in JSON format for scripts
codebase search "auth" --json

⚙️ Configuração

Camadas de Configuração (Ordem de Prioridade)

1. Argumentos CLI - Parâmetros de tempo de execução (--path, --config, --log-level, --force, etc.)
2. Configuração do Projeto - ./autodev-config.json (ou caminho personalizado via --config)
3. Configuração Global - ~/.autodev-cache/autodev-config.json
4. Padrões Internos - Valores de fallback

Nota: Os argumentos CLI fornecem substituição em tempo de execução para caminhos, registro de logs e comportamento operacional. Para configuração persistente (embedderProvider, chaves de API, parâmetros de busca), use config --set para salvar nos arquivos de configuração.

Exemplos Comuns de Configuração

Ollama:

{
  "embedderProvider": "ollama",
  "embedderModelId": "nomic-embed-text",
  "qdrantUrl": "http://localhost:6333"
}

OpenAI:

{
  "embedderProvider": "openai",
  "embedderModelId": "text-embedding-3-small",
  "embedderOpenAiApiKey": "sk-your-key",
  "qdrantUrl": "http://localhost:6333"
}

Compatível com OpenAI:

{
  "embedderProvider": "openai-compatible",
  "embedderModelId": "text-embedding-3-small",
  "embedderOpenAiCompatibleApiKey": "sk-your-key",
  "embedderOpenAiCompatibleBaseUrl": "https://api.openai.com/v1"
}

Principais Opções de Configuração

Categoria	Opções	Descrição
Embedding	embedderProvider, embedderModelId, embedderModelDimension	Configurações de provedor e modelo
Chaves de API	embedderOpenAiApiKey, embedderOpenAiCompatibleApiKey	Autenticação
Armazenamento Vetorial	qdrantUrl, qdrantApiKey	Conexão Qdrant
Busca	vectorSearchMinScore, vectorSearchMaxResults	Comportamento de busca
Reordenador	rerankerEnabled, rerankerProvider	Reordenação de resultados
Resumidor	summarizerProvider, summarizerLanguage, summarizerBatchSize	Geração de resumos com IA

Principais Argumentos CLI:

• index - Indexa o codebase
• search <query> - Busca no codebase (argumento posicional obrigatório)
• outline <pattern> - Extrai esboços de código (suporta padrões glob)
• call - Analisa relações de chamadas de funções e grafos de dependência
• stdio - Inicia o adaptador stdio para MCP
• config - Gerencia a configuração (use com --get ou --set)
• --serve - Inicia o servidor HTTP MCP (use com o comando index)
• --summarize - Gera resumos de IA para esboços de código
• --dry-run - Pré-visualiza operações antes da execução
• --title - Mostra apenas resumos em nível de arquivo
• --clear-summarize-cache - Limpa todos os caches de resumo
• --path, --demo, --force - Opções comuns
• --limit / -l <number> - Número máximo de resultados de busca (padrão: da configuração, máx. 50)
• --min-score / -S <number> - Pontuação mínima de similaridade para resultados de busca (0-1, padrão: da configuração)
• --query <patterns> - Padrões de consulta para análise de grafo de chamadas (separados por vírgula)
• --viz <file> - Exporta dados completos de dependência para visualização (não pode ser usado com --query)
• --open - Abre o visualizador interativo de grafos
• --depth <number> - Define a profundidade de análise para grafos de chamadas
• --help - Mostra todas as opções disponíveis

Comandos de Configuração:

# View config
codebase config --get
codebase config --get --json

# Set config (saves to file)
codebase config --set embedderProvider=ollama,embedderModelId=nomic-embed-text
codebase config --set --global embedderProvider=openai,embedderOpenAiApiKey=sk-xxx

# Use custom config file
codebase --config=/path/to/config.json config --get
codebase --config=/path/to/config.json config --set embedderProvider=ollama

# Runtime override (paths, logging, etc.)
codebase index --path=/my/project --log-level=info --force

Para referência completa de configuração, consulte CONFIG.md.

🔌 Integração MCP

Modo HTTP Streamable (Recomendado)

codebase index --serve --port=3001

Configuração IDE:

{
  "mcpServers": {
    "codebase": {
      "url": "http://localhost:3001/mcp"
    }
  }
}

Adaptador Stdio

# First start the MCP server in one terminal
codebase index --serve --port=3001

# Then connect via stdio adapter in another terminal (for IDEs that require stdio)
codebase stdio --server-url=http://localhost:3001/mcp

Configuração IDE:

{
  "mcpServers": {
    "codebase": {
      "command": "codebase",
      "args": ["stdio", "--server-url=http://localhost:3001/mcp"]
    }
  }
}

🤝 Contribuições

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request ou abrir uma Issue no GitHub.

📄 Licença

Este projeto é licenciado sob a Licença MIT.

🙏 Agradecimentos

Este projeto é um fork e trabalho derivado baseado no Roo Code. Construímos sobre sua excelente base para criar esta ferramenta especializada de análise de codebase com recursos aprimorados e capacidades de servidor MCP.

---