Octocode MCP

Octocode: plataforma de pesquisa agentica

Pesquisa de código baseada em evidências para agentes de IA e desenvolvedores.

O Octocode pesquisa seu código local e código externo igualmente (repositórios GitHub, PRs, npm) com um único conjunto de ferramentas: ripgrep + busca AST, árvores, leituras precisas e LSP. Use-o como CLI ou servidor MCP, com suporte de um mecanismo Rust para resultados rápidos e eficientes em tokens, em arquivos únicos ou mega-repositórios.

Sumário

• Início rápido
• Por que Octocode
• Feito para pesquisa (benchmarks)
• Ferramentas
• MCP
• CLI
• Configuração
• Métodos de autenticação
• Segurança
• Suporte a linguagens
• Habilidades
• Arquitetura
• Documentação
• Solução de problemas
• Fluxos de trabalho para agentes

Início rápido

Pré-requisitos: Node.js 20.12+

1. Execute o CLI do Octocode com npx

npx octocode --help

2. Autentique-se com o GitHub - opcional, mas desbloqueia repositórios privados e limites de taxa de API mais altos:

npx octocode auth login
npx octocode status       # verify the active token source

3. Escolha sua interface. Mesmas ferramentas e mecanismo Rust em ambas. (A clonagem é ativada por padrão no CLI, opt-in para MCP.)

🖥️ CLI - pesquise direto do seu terminal:

npx octocode

🤖 MCP - instalação com um clique:

claude mcp add-json octocode --scope user '{"command":"npx","type":"stdio","args":["octocode-mcp@latest"]}'

Qualquer outro cliente: npx octocode install

Use como servidor MCP

Adicione à configuração do seu cliente MCP (ou use uma instalação com um clique acima):

{
  "octocode": {
    "command": "npx",
    "type": "stdio",
    "args": ["octocode-mcp@latest"]
  }
}

Coloque um token do GitHub e opções em env (veja Configuração).

Use como CLI amigável para agentes

Execute npx octocode e os agentes descobrem o resto. O comando simples imprime o uso integrado e o catálogo completo de ferramentas, para que qualquer agente de codificação saiba como usá-lo imediatamente, sem cliente MCP ou configuração extra.

npx octocode                                         # self-describing usage for agents
npx octocode tools                                   # list every tool
npx octocode tools localSearchCode --scheme          # inspect a tool's schema

Cada ferramenta MCP também é um comando simples: JSON na entrada, YAML eficiente em tokens na saída. Caminhos locais roteiam para ferramentas locais; owner/repo[/path] roteia para o GitHub.

npx octocode tools localSearchCode \
  --queries '{"path":".","searchText":"authenticate","maxFiles":20}'

results:
  - id: localSearchCode-1
    data:
      files:
        - path: src/auth.ts
          matches:
            - line: 12
              value: "export async function authenticate(req: Request) {"

Saiba mais em octocode.ai.

Por que Octocode

Agentes codificam melhor com evidências do que com suposições. O Octocode pesquisa dois mundos com um único fluxo, seu código local e código externo no GitHub e npm, e devolve contexto compacto e citável antes que um agente altere, revise ou explique código. Código é verdade; contexto é o mapa.

A maioria das ferramentas faz uma parte (busca na web ou grep no seu repositório) e devolve um bloco fixo. O Octocode cobre o ciclo completo e permite que o agente decida quais dados precisa em seguida:

• Fluxos eficientes e orientados por agente. Em vez de despejos de uma única vez, o Octocode encadeia etapas baratas em um fluxo de pesquisa otimizado: busca ampla de código, depois busca apenas as linhas/regiões exatas correspondentes, com paginação inteligente e minificação pronta para uso, para que o modelo nunca busque demais. Cada resultado traz dicas de próximos passos para o acompanhamento mais barato.
• Escala para monorepos. Identifique um padrão em um repositório, siga o PR que o introduziu e rastreie-o em outros repositórios e seus próprios arquivos, sem sair do chat. Clone qualquer repositório e estude-o localmente.
• Fluxo GitHub inteligente. Consultas paralelas em lote em código, PRs, commits, issues e repositórios, todas com a mesma disciplina de buscar amplo, ler com precisão e rastrear semanticamente.
• Funciona sem GitHub. Clone qualquer repositório e aponte as ferramentas locais (busca, AST, LSP, conteúdo) para ele, com o mesmo fluxo baseado em evidências.
• Lê a forma, não o ruído. Minificação/esqueletização em tempo real em mais de 70 linguagens: um arquivo de 100 KB em algumas centenas de tokens, não paredes de código repetitivo.
• Rápido e autossuficiente. Busca, análise, navegação e redação rodam em um mecanismo Rust pré-compilado: rápido em um laptop ou mega-repositório, sem nada extra para instalar.
• Seguro por padrão. Cada byte enviado ao modelo é verificado e segredos são redigidos primeiro (veja Segurança).

O que você pode fazer (quando o próximo passo precisar de contexto comprovado, não de suposição):

Feito para pesquisa (benchmarks)

Um teste cego, frente a frente, em fluxos orientados a pesquisa em vez de buscas simples (rastreamentos multi-etapas, cadeias de dependência/grafo de chamadas, intervalos de commits, raio de impacto, revisões de PR entre repositórios).

Como funciona: 30 perguntas do GitHub × 3 execuções; Octocode vs gh, gh+Headroom e gh+RTK em perguntas idênticas (apenas o CLI difere). Um juiz cego (gpt-5.5) avalia a correção; a métrica é caracteres através do modelo, contados a partir de logs instrumentados (caracteres, não tokens). Resultado: com correção quase idêntica, o Octocode responde com ~2,0× menos caracteres que gh puro, ~2,6× menos que gh+Headroom e ~3,2× menos que gh+RTK nas execuções principais da build local.

▶ Abra o relatório interativo · execute-o / método · perguntas · todos os relatórios

Ferramentas

17 ferramentas no catálogo completo. Quantas são registradas depende da superfície e das flags que você define:

ghListReleases e ghSearchDiscussions precisam de duas configurações no MCP, não apenas uma: ENABLE_RELEASES=1 ou ENABLE_DISCUSSIONS=1 coloca a ferramenta no catálogo, e ENABLE_TOOLS="ghListReleases,ghSearchDiscussions" a registra. Qualquer configuração isolada deixa a ferramenta não registrada, porque ambas carregam isDefault: false e o filtro de registro do MCP admite apenas ferramentas padrão ou explicitamente na allowlist. O CLI precisa apenas das flags ENABLE_RELEASES e ENABLE_DISCUSSIONS. ENABLE_LOCAL e ENABLE_CLONE aceitam true ou 1; ENABLE_RELEASES e ENABLE_DISCUSSIONS também aceitam yes e on. Flags: Configuração.

Controles de tokens. concise:true retorna listas apenas com caminho/título. minify controla a densidade de leitura de arquivos: symbols = esqueleto com números de linha, standard = comentários/linhas em branco removidos (padrão), none = bytes exatos.

Ferramentas do GitHub

Ferramentas locais

Busca de pacotes

LSP

Esquemas completos, campos e exemplos para cada ferramenta estão em docs/OCTOCODE_TOOLS.md (linkado em Documentação).

MCP

O servidor MCP expõe o catálogo de ferramentas do Octocode diretamente ao seu assistente de IA via stdio.

https://github.com/user-attachments/assets/de8d14c0-2ead-46ed-895e-09144c9b5071

Configuração manual

Adicione à configuração do seu cliente MCP, usando octocode-mcp:

{
  "octocode": {
    "command": "npx",
    "type": "stdio",
    "args": [
      "octocode-mcp@latest"
    ]
  }
}

Adicione um token do GitHub e opções em env - veja Autenticação e Configuração.

CLI

Mesmo mecanismo de pesquisa, sem necessidade de cliente MCP. Caminhos locais roteiam para ferramentas locais; owner/repo[/path] roteia para o GitHub. Autentique-se uma vez com npx octocode auth login (veja Autenticação); execute npx octocode --help para uso completo.

Comandos

Comandos de ferramentas

Mais comandos

• Cache e clone — npx octocode clone, npx octocode cache fetch|status|clear
• Habilidades — npx octocode skill list|install|check|info|remove para habilidades Octocode inclusas
• Servidores de linguagem — npx octocode lsp-server list|install|status|uninstall|clean
• Configuração e introspecção — npx octocode install, npx octocode auth, npx octocode status, npx octocode context

Sintaxe completa, flags e códigos de saída: Guia da CLI Octocode

Configuração

Tudo é opcional; o Octocode funciona com padrões sensatos. As configurações são resolvidas de três fontes, em ordem de prioridade:

environment variables  >  <octocode-home>/.octocoderc  >  built-in defaults

1. Variáveis MCP / de ambiente (maior prioridade): por cliente ou por projeto, definidas na configuração MCP env ou no seu shell.
2. Configuração global: <octocode-home>/.octocoderc, padrões de toda a máquina lidos tanto pela CLI quanto pelo servidor MCP.
3. Padrões embutidos: usados quando nenhum dos anteriores está definido.

Diretório inicial do Octocode (<octocode-home>) contém a configuração global, credenciais criptografadas, sessões, estatísticas e caches de materialização temporária. Em todas as plataformas, é .octocode dentro do diretório inicial do sistema operacional — ~/.octocode no macOS e Linux, %USERPROFILE%\.octocode no Windows. Substitua-o com OCTOCODE_HOME.

Defina valores como entradas MCP env (por cliente; estas têm precedência sobre .octocoderc) ou globalmente em <octocode-home>/.octocoderc (JSON com comentários). Tokens nunca vão em .octocoderc — use env ou npx octocode auth login.

Configurações comuns

Configurações mais usadas (tanto CLI quanto MCP, salvo indicação):

OCTOCODE_HOME, GitHub Enterprise (GITHUB_API_URL), lista de permissão de ferramentas MCP (TOOLS_TO_RUN/ENABLE_TOOLS/DISABLE_TOOLS) e tempos limite/repetições de rede: veja a Referência de Configuração.

Exemplo de configuração

~/.octocode/.octocoderc:

{
  "github": {
    "apiUrl": "https://api.github.com"
  },
  "local": {
    "enabled": true,
    "enableClone": true
  },
  "output": {
    "format": "yaml"
  }
}

Substituições por projeto e servidores LSP personalizados ficam em uma pasta .octocode/ do espaço de trabalho. Para o esquema completo de .octocoderc, um exemplo pronto para copiar, ajuste de cache de clone, configuração do GitHub Enterprise e detalhes de precedência, veja a Referência de Configuração.

Métodos de autenticação

Ferramentas baseadas no GitHub exigem autenticação. Qualquer um dos métodos é suficiente. Detalhes completos: Configuração de Autenticação.

Opção 1: CLI do Octocode (recomendada)

npx octocode auth login
npx octocode status       # verify the active token source

O login interativo permite escolher OAuth do navegador Octocode ou gh auth login. As credenciais OAuth do Octocode são armazenadas criptografadas em disco.

Opção 2: GitHub CLI (também suportado)

gh auth login

O Octocode lê o token gh automaticamente — nenhuma configuração adicional é necessária.

Opção 3: Token de acesso pessoal (também suportado)

Defina OCTOCODE_TOKEN, GH_TOKEN ou GITHUB_TOKEN no seu shell. Escopos necessários: repo, read:user, read:org.

Crie um token em github.com/settings/tokens.

Nota: Nunca envie tokens para o controle de versão. Use variáveis de ambiente ou gerenciamento seguro de segredos.

Segurança

Cada byte enviado ao modelo é escaneado e redigido primeiro. Todo o conteúdo passa pelo scanner de segredos do mecanismo Rust no caminho de entrada e saída, então segredos nunca chegam ao modelo. Isso cobre arquivos locais, respostas do GitHub e npm, erros e saída de ferramentas. O comportamento é idêntico sob MCP e CLI.

• Redação de segredos, na entrada e na saída. Mais de 300 padrões de credenciais de provedores (AWS, Azure, GCP, GitHub, OpenAI, Anthropic, Stripe, Slack, 1Password e mais) além de JWTs genéricos, chaves PEM/privadas, tokens de portador, strings de conexão de banco de dados e strings de alta entropia. Valores mascarados exibem um aviso de redação para que o agente saiba.
• Conteúdo sanitizado na origem. Leituras locais (localGetFileContent, ripgrep, busca estrutural, binário, descoberta de arquivos, estrutura) e buscas externas (código/arquivos do GitHub, npm) são escaneadas conforme são lidas, não apenas no limite.
• Segurança de caminhos. Entradas relativas são resolvidas a partir de WORKSPACE_ROOT / configuração / cwd, então leituras locais são limitadas às raízes permitidas do mecanismo (home por padrão, além de ALLOWED_PATHS e raízes registradas pelo Octocode). Links simbólicos são resolvidos e o destino real é revalidado, para que um link não possa escapar para um local bloqueado.
• Arquivos sensíveis bloqueados por padrão. Leituras de arquivos e pastas conhecidos por conter segredos retornam um erro redigido em vez do conteúdo: chaves/certificados, .env*, .npmrc/.netrc, credenciais de nuvem/infraestrutura (.aws/, .kube/, *.tfstate), .git/, logins de navegador, chaveiros do sistema operacional e carteiras. Lista completa em SECURITY.md.
• Segurança de comandos. A busca local normal é executada em processo dentro de octocode-engine. Auxiliares externos são fixos por faixa, com lista de permissão de comando/argumento e executados via spawn com matrizes de argumentos: sem strings de shell, sem injeção.
• Validação de esquema é executada antes de qualquer ferramenta; tamanho e forma de entrada não confiável são limitados.
• Credenciais. Autenticação do GitHub por tokens de ambiente, OAuth criptografado em disco com AES-256-GCM ou a CLI gh; tokens nunca são registrados em log.

Modelo de segurança completo, pipeline e cobertura de ameaças: SECURITY.md. Relacionados: Configuração e autenticação · Credenciais

Suporte a linguagens

Quatro eixos de inteligência de código; três são nativos do mecanismo Rust e não precisam de ferramentas externas:

📋 Matriz de suporte completa: cada extensão com sua capacidade exata de AST, assinatura, LSP e minificação está na Matriz completa de formatos suportados.

Habilidades

Agent Skills são um formato leve e aberto para estender capacidades de agentes de IA. Navegue e instale em skills.sh/bgauryy/octocode-mcp

13 habilidades em skills/, incluídas no pacote octocode. Cada uma é um SKILL.md enxuto que carrega referências apenas quando necessário, então elas se compõem. Comece com ⭐ Research para trabalho de código com foco em evidências.

npx octocode skill list
npx octocode skill install octocode-research --platform pi
npx octocode skill check --json
npx octocode skill help

Pesquisa e extração principais

Planejamento e arquitetura

Avaliação e revisão

Orquestração de agentes

Fluxo de trabalho de automação web: octocode-scraping executa a passagem estática segura primeiro (busca/rastreamento/extração → corpus local → grafo v2). Quando o grafo expõe ações dinâmicas ou a saída estática é bloqueada/escassa, octocode-chrome-devtools valida a ação ao vivo, cookies/armazenamento, corpos de rede/HAR, capturas de tela ou estado com autenticação; URLs/dados/artefatos descobertos podem ser realimentados no corpus de raspagem para prova contínua.

Arquitetura

Um monorepo de workspaces yarn. O servidor MCP e a CLI são front-ends finos sobre um núcleo de ferramentas TypeScript compartilhado, que delega cada caminho pesado de CPU a um único mecanismo Rust (compilado via napi-rs para binários .node pré-compilados). Um catálogo de ferramentas, uma camada de segurança, um modelador de respostas, alcançado de duas maneiras.

graph LR
    CLI["octocode<br/>CLI"]
    MCP["octocode-mcp<br/>MCP server, stdio"]
    VSC["VS Code extension<br/>OAuth + install"]
    CORE["octocode-tools-core<br/>tools, GitHub client, auth, pagination, security bridge"]
    ENGINE["octocode-engine (Rust)<br/>secrets, minify, AST, signatures, ripgrep/diff/YAML, LSP"]
    EXT["GitHub API, local FS + ripgrep, language servers"]

    CLI --> CORE
    MCP --> CORE
    VSC -. starts .-> MCP
    CORE --> ENGINE
    CORE --> EXT
    ENGINE --> EXT

    style ENGINE fill:#1a1a2e,stroke:#e75d2a,color:#fff

Fluxo de solicitação é idêntico, seja uma chamada via MCP ou CLI:

client → sanitize inputs (Rust) → run tool (GitHub / FS / LSP) → sanitize + YAML-serialize + paginate (Rust) → result + next-step hints

Um mecanismo Rust é dono da detecção de segredos, sanitização, validação de caminhos e comandos, minificação (mais de 70 linguagens), extração de assinaturas, busca estrutural AST, análise ripgrep, filtragem de diffs, serialização YAML e LSP. O loop de eventos do Node permanece, portanto, desbloqueado, e não há carregador nativo duplicado. O mecanismo é enviado pré-compilado para darwin (arm64/x64), linux (arm64/x64, gnu e musl) e win32-x64; nenhuma toolchain Rust é necessária em tempo de execução.

Pacotes

packages/octocode-benchmark (privado, não publicado) contém metodologia de benchmark, avaliações e artefatos de execução - veja Documentação.

Documentação

Site: octocode.ai · Documentação do produto: github.com/bgauryy/octocode/tree/main/docs. Esta seção é o índice canônico da documentação; metodologia de benchmark, avaliações e artefatos de execução estão em packages/octocode-benchmark.

Solução de problemas

Problemas com Node.js ou ambiente? Execute o comando doctor integrado para verificar seu ambiente:

npx node-doctor

Armadilhas comuns:

• Falhas de autenticação do GitHub: Garanta que seu Personal Access Token (PAT) tenha os escopos repo e read:user. Se estiver usando a CLI, execute npx octocode auth login para atualizar.
• Problemas de conexão MCP: Se seu assistente de IA (como Cursor ou Windsurf) falhar ao conectar, garanta que você executou npx octocode auth login no seu terminal primeiro, ou passe explicitamente seu OCTOCODE_TOKEN na configuração env do MCP.
• Erros do motor nativo: Octocode usa um motor Rust pré-compilado. Se ele falhar ao carregar no Linux, garanta que seu sistema tenha compatibilidade com glibc ou musl. No macOS/Windows, garanta que você está em uma arquitetura suportada (x64 ou arm64).

Fluxos de trabalho de agentes

Modo de desenvolvimento recomendado: Pi + Octocode

Pi é um agente de codificação rápido e local-first cuja filosofia declarada é "ferramentas CLI com READMEs (Skills) em vez de MCP." Combiná-lo com Octocode oferece um ciclo de desenvolvimento enxuto e orientado a evidências — Pi edita, Octocode pesquisa. Duas rotas, escolha conforme a superfície que você precisa:

• Rota de skill — recomendada, mais enxuta. Coloque a skill octocode-research no diretório global de skills do Pi. Ela aciona a CLI do Octocode diretamente — sem transporte MCP, sobrecarga mínima de tokens — e o Pi a descobre automaticamente:

  npx octocode skill install octocode-research --platform pi
  

• Rota de adaptador — superfície completa de ferramentas. Instale pi-mcp-adapter para expor as ferramentas MCP do Octocode por trás de uma única ferramenta proxy de ~200 tokens, para que os servidores permaneçam desconectados até que uma ferramenta seja chamada. Habilite ferramentas de clone com ENABLE_CLONE=true.

Ciclo orientado a pesquisa

A maioria das falhas de agentes acontece antes da edição: adivinhar quem é dono de um comportamento, confiar em um trecho sem ler a fonte, editar antes de provar o raio de impacto. Execute um ciclo mais barato: oriente-se com árvores, pesquise, leia evidências exatas, use AST/LSP quando a identidade importar, depois aplique o patch e verifique. O host edita, Octocode é o mapa, e as skills codificam o hábito.

O Manifesto

"Código é a Verdade, mas Contexto é o Mapa." Leia o Manifesto do Octocode para Desenvolvimento Orientado a Pesquisa para entender a filosofia por trás do Octocode.