Octocode MCP

Octocode: plataforma de investigación agéntica

Investigación de código basada en evidencia para agentes de IA y desarrolladores.

Octocode investiga tanto tu código local como código externo (repositorios de GitHub, PRs, npm) con un solo conjunto de herramientas: ripgrep + búsqueda AST, árboles, lecturas precisas y LSP. Úsalo como CLI o servidor MCP, respaldado por un motor Rust para resultados rápidos y eficientes en tokens, ya sea en archivos individuales o mega-repositorios.

Tabla de contenidos

• Inicio rápido
• Por qué Octocode
• Diseñado para investigación (benchmarks)
• Herramientas
• MCP
• CLI
• Configuración
• Métodos de autenticación
• Seguridad
• Soporte de lenguajes
• Habilidades
• Arquitectura
• Documentación
• Solución de problemas
• Flujos de trabajo para agentes

Inicio rápido

Requisitos previos: Node.js 20.12+

1. Ejecuta el CLI de Octocode con npx

npx octocode --help

2. Autentícate con GitHub - opcional, pero desbloquea repositorios privados y límites de tasa de API más altos:

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

3. Elige tu interfaz. Mismas herramientas y motor Rust en ambas. (La clonación está activada por defecto en el CLI, opt-in para MCP).

🖥️ CLI - investiga directamente desde tu terminal:

npx octocode

🤖 MCP - instalación con un clic:

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

Cualquier otro cliente: npx octocode install

Úsalo como servidor MCP

Agrégalo a la configuración de tu cliente MCP (o usa una instalación con un clic de arriba):

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

Coloca un token de GitHub y opciones bajo env (consulta Configuración).

Úsalo como CLI amigable para agentes

Ejecuta npx octocode y los agentes resuelven el resto. El comando básico imprime el uso integrado y el catálogo completo de herramientas, para que cualquier agente de codificación sepa cómo usarlo desde el primer momento, sin cliente MCP ni cableado adicional.

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

Cada herramienta MCP también es un comando simple: JSON de entrada, YAML eficiente en tokens de salida. Las rutas locales se dirigen a herramientas locales; owner/repo[/path] se dirige a 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) {"

Aprende más en octocode.ai.

Por qué Octocode

Los agentes codifican mejor con evidencia que con suposiciones. Octocode investiga dos mundos con un solo flujo: tu código local y código externo en GitHub y npm, y devuelve contexto compacto y citable antes de que un agente modifique, revise o explique código. El código es la verdad; el contexto es el mapa.

La mayoría de las herramientas hacen una sola parte (búsqueda web, o grep en tu repositorio) y devuelven un bloque fijo. Octocode cubre todo el ciclo y permite que el agente decida qué datos necesita a continuación:

• Flujos eficientes impulsados por el agente. En lugar de volcados de una sola vez, Octocode encadena pasos económicos en un flujo de investigación optimizado: búsqueda amplia de código, luego recupera solo las líneas/regiones exactas coincidentes, con paginación inteligente y minificación integrada para que el modelo nunca sobrecargue. Cada resultado incluye pistas de siguientes pasos hacia la acción de seguimiento más económica.
• Escala a monorepositorios. Detecta un patrón en un repositorio, sigue el PR que lo introdujo, luego trázalo en otros repositorios y tus propios archivos, sin salir del chat. Clona cualquier repositorio y estúdialo localmente.
• Flujo inteligente de GitHub. Consultas masivas en paralelo en código, PRs, commits, issues y repositorios, todo con la misma disciplina de buscar amplio, leer con precisión y rastrear semánticamente.
• Funciona sin GitHub. Clona cualquier repositorio y apunta las herramientas locales (búsqueda, AST, LSP, contenido) hacia él, con el mismo flujo basado en evidencia.
• Lee la forma, no el ruido. Minificación/esqueletización sobre la marcha en más de 70 lenguajes: un archivo de 100 KB en unos pocos cientos de tokens, no muros de código repetitivo.
• Rápido y autónomo. Búsqueda, análisis, navegación y redacción se ejecutan en un motor Rust precompilado: rápido en una laptop o en un mega-repositorio, sin nada extra que instalar.
• Seguro por defecto. Cada byte enviado al modelo se escanea y los secretos se redactan primero (consulta Seguridad).

Lo que puedes hacer (cuando el siguiente paso necesite contexto probado, no una suposición):

Diseñado para investigación (benchmarks)

Una prueba ciega, cara a cara, en flujos orientados a la investigación en lugar de búsquedas simples (trazas de múltiples saltos, cadenas de dependencias/grafos de llamadas, rangos de commits, radio de impacto, revisiones de PRs entre repositorios).

Cómo funciona: 30 preguntas de GitHub × 3 pasadas; Octocode vs gh, gh+Headroom y gh+RTK en preguntas idénticas (solo difiere el CLI). Un juez ciego (gpt-5.5) califica la corrección; la métrica es caracteres a través del modelo, contados desde registros instrumentados (caracteres, no tokens). Resultado: con corrección casi idéntica, Octocode responde con ~2.0× menos caracteres que gh simple, ~2.6× menos que gh+Headroom y ~3.2× menos que gh+RTK en las ejecuciones principales de la compilación local.

▶ Abre el informe interactivo · ejecútalo / método · preguntas · todos los informes

Herramientas

17 herramientas en el catálogo completo. Cuántas se registran depende de la superficie y las banderas que establezcas:

ghListReleases y ghSearchDiscussions necesitan dos configuraciones en MCP, no una: ENABLE_RELEASES=1 o ENABLE_DISCUSSIONS=1 coloca la herramienta en el catálogo, y ENABLE_TOOLS="ghListReleases,ghSearchDiscussions" la registra. Cualquiera de las dos configuraciones por sí sola deja la herramienta sin registrar, porque ambas llevan isDefault: false y el filtro de registro de MCP solo admite herramientas predeterminadas o explícitamente permitidas. El CLI solo necesita las banderas ENABLE_RELEASES y ENABLE_DISCUSSIONS. ENABLE_LOCAL y ENABLE_CLONE aceptan true o 1; ENABLE_RELEASES y ENABLE_DISCUSSIONS también aceptan yes y on. Banderas: Configuración.

Controles de tokens. concise:true devuelve listas solo de ruta/título. minify controla la densidad de lectura de archivos: symbols = esqueleto con números de línea, standard = comentarios/espacios en blanco eliminados (predeterminado), none = bytes exactos.

Herramientas de GitHub

Herramientas locales

Búsqueda de paquetes

LSP

Los esquemas completos, campos y ejemplos de cada herramienta están en docs/OCTOCODE_TOOLS.md (enlazado bajo Documentación).

MCP

El servidor MCP expone el catálogo de herramientas de Octocode directamente a tu asistente de IA a través de stdio.

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

Configuración manual

Agrégalo a la configuración de tu cliente MCP, usando octocode-mcp:

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

Agrega un token de GitHub y opciones bajo env - consulta Autenticación y Configuración.

CLI

Same research engine, no MCP client needed. Local paths route to local tools; owner/repo[/path] routes to GitHub. Authenticate once with npx octocode auth login (see Authentication); run npx octocode --help for full usage.

Commands

Tool commands

More commands

• Cache and clone — npx octocode clone, npx octocode cache fetch|status|clear
• Skills — npx octocode skill list|install|check|info|remove for bundled Octocode skills
• Language servers — npx octocode lsp-server list|install|status|uninstall|clean
• Setup and introspection — npx octocode install, npx octocode auth, npx octocode status, npx octocode context

Full syntax, flags, and exit codes: Octocode CLI guide

Configuration

Everything is optional; Octocode runs on sensible defaults. Settings resolve from three sources, in priority order:

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

1. MCP / environment variables (highest): per client or per project, set in your MCP config env or your shell.
2. Global config: <octocode-home>/.octocoderc, machine-wide defaults read by both the CLI and the MCP server.
3. Built-in defaults: used when neither is set.

Octocode home (<octocode-home>) holds the global config, encrypted credentials, sessions, stats, and tmp materialization caches. On every platform it is .octocode inside the OS home directory — ~/.octocode on macOS and Linux, %USERPROFILE%\.octocode on Windows. Override it with OCTOCODE_HOME.

Set values as MCP env entries (per client; these win over .octocoderc) or globally in <octocode-home>/.octocoderc (JSON with comments). Tokens never go in .octocoderc — use env or npx octocode auth login.

Common settings

Most-used settings (both CLI and MCP unless noted):

OCTOCODE_HOME, GitHub Enterprise (GITHUB_API_URL), MCP tool allowlisting (TOOLS_TO_RUN/ENABLE_TOOLS/DISABLE_TOOLS), and network timeouts/retries: see the Configuration Reference.

Example configuration

~/.octocode/.octocoderc:

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

Per-project overrides and custom LSP servers live in a workspace .octocode/ folder. For the full .octocoderc schema, a ready-to-copy example, clone-cache tuning, GitHub Enterprise setup, and precedence details, see the Configuration Reference.

Authentication methods

GitHub-backed tools require authentication. Any one method is enough. Full details: Authentication Setup.

Option 1: Octocode CLI (recommended)

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

Interactive login lets you choose Octocode browser OAuth or gh auth login. Octocode OAuth credentials are stored encrypted on disk.

Option 2: GitHub CLI (also supported)

gh auth login

Octocode reads the gh token automatically — no further config needed.

Option 3: Personal access token (also supported)

Set OCTOCODE_TOKEN, GH_TOKEN, or GITHUB_TOKEN in your shell. Required scopes: repo, read:user, read:org.

Create a token at github.com/settings/tokens.

Note: Never commit tokens to version control. Use environment variables or secure secret management.

Security

Every byte to the model is scanned and redacted first. All content passes through the Rust engine's secret scanner on the way in and out, so secrets never reach the model. That covers local files, GitHub and npm responses, errors, and tool output. The behavior is identical under MCP and the CLI.

• Secret redaction, in and out. 300+ provider credential patterns (AWS, Azure, GCP, GitHub, OpenAI, Anthropic, Stripe, Slack, 1Password, and more) plus generic JWTs, PEM/private keys, bearer tokens, database connection strings, and high-entropy strings. Masked values surface a redaction warning so the agent knows.
• Content sanitized at the source. Local reads (localGetFileContent, ripgrep, structural search, binary, file discovery, structure) and external fetches (GitHub code/files, npm) are scanned as they are read, not only at the boundary.
• Path safety. Relative inputs resolve from WORKSPACE_ROOT / config / cwd, then local reads are bounded to the engine's allowed roots (home by default, plus ALLOWED_PATHS and Octocode-registered roots). Symlinks are resolved and the real target is re-validated, so a link cannot escape into a blocked location.
• Sensitive files blocked by default. Reads of known secret-bearing files and folders return a redacted error instead of contents: keys/certs, .env*, .npmrc/.netrc, cloud/infra credentials (.aws/, .kube/, *.tfstate), .git/, browser logins, OS keychains, and wallets. Full list in SECURITY.md.
• Command safety. Normal local search runs in-process inside octocode-engine. External helpers are fixed per lane, command/argument allowlisted, and run through spawn with argument arrays: no shell strings, no injection.
• Schema validation runs before any tool executes; untrusted input size and shape are bounded.
• Credentials. GitHub auth through env tokens, AES-256-GCM-encrypted on-disk OAuth, or the gh CLI; tokens are never logged.

Full security model, pipeline, and threat coverage: SECURITY.md. Related: Configuration and authentication · Credentials

Language support

Four code-intelligence axes; three are native to the Rust engine and need no external tooling:

📋 Full support matrix: every extension with its exact AST, signature, LSP, and minify capability lives in the Full format support matrix.

Skills

Agent Skills are a lightweight, open format for extending AI agent capabilities. Browse and install on skills.sh/bgauryy/octocode-mcp

13 skills under skills/, bundled in the octocode package. Each is a lean SKILL.md that loads references only when needed, so they compose. Start with ⭐ Research for evidence-first code work.

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

Core research and extraction

Planning and architecture

Evaluation and review

Agent orchestration

Web automation workflow: octocode-scraping performs the safe static pass first (fetch/crawl/extract → local corpus → graph v2). When the graph exposes dynamic actions or static output is blocked/thin, octocode-chrome-devtools validates live actionability, cookies/storage, network/HAR bodies, screenshots, or auth-gated state; discovered URLs/data/artifacts can be fed back into the scraping corpus for continued proof.

Architecture

A yarn-workspaces monorepo. The MCP server and the CLI are thin front-ends over one shared TypeScript tool core, which delegates every CPU-heavy path to a single Rust engine (compiled through napi-rs to prebuilt .node binaries). One tool catalog, one security layer, one response shaper, reached two ways.

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

Request flow is identical whether a call arrives over MCP or the CLI:

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

One Rust engine owns secret detection, sanitization, path and command validation, minification (70+ languages), signature extraction, structural AST search, ripgrep parsing, diff filtering, YAML serialization, and LSP. The Node event loop therefore stays unblocked, and there is no duplicate native loader. The engine ships prebuilt for darwin (arm64/x64), linux (arm64/x64, gnu and musl), and win32-x64; no Rust toolchain is needed at runtime.

Packages

packages/octocode-benchmark (privado, no publicado) contiene la metodología de benchmarks, evaluaciones y artefactos de ejecución; consulta Documentación.

Documentación

Sitio web: octocode.ai · Documentación del producto: github.com/bgauryy/octocode/tree/main/docs. Esta sección es el índice canónico de documentación; la metodología de benchmarks, evaluaciones y artefactos de ejecución viven en packages/octocode-benchmark.

Solución de problemas

¿Problemas con Node.js o el entorno? Ejecuta el comando de diagnóstico integrado para verificar tu entorno:

npx node-doctor

Errores comunes:

• Fallos de autenticación de GitHub: Asegúrate de que tu Personal Access Token (PAT) tenga los alcances repo y read:user. Si usas la CLI, ejecuta npx octocode auth login para actualizar.
• Problemas de conexión MCP: Si tu asistente de IA (como Cursor o Windsurf) no puede conectarse, asegúrate de haber ejecutado npx octocode auth login en tu terminal primero, o pasa explícitamente tu OCTOCODE_TOKEN en la configuración de MCP env.
• Errores del motor nativo: Octocode usa un motor Rust precompilado. Si falla al cargar en Linux, asegúrate de que tu sistema tenga compatibilidad con glibc o musl. En macOS/Windows, asegúrate de estar en una arquitectura compatible (x64 o arm64).

Flujos de trabajo de agentes

Modo de desarrollo recomendado: Pi + Octocode

Pi es un agente de codificación rápido y local-first cuya filosofía declarada es "CLI tools with READMEs (Skills) over MCP." Combinarlo con Octocode ofrece un bucle de desarrollo ágil y basado en evidencia — Pi edita, Octocode investiga. Dos rutas, elige según cuánta superficie necesites:

• Ruta de skills — recomendada, la más ágil. Coloca el skill octocode-research en el directorio global de skills de Pi. Este impulsa la CLI de Octocode directamente — sin transporte MCP, con un gasto mínimo de tokens — y Pi lo descubre automáticamente:

  npx octocode skill install octocode-research --platform pi
  

• Ruta de adaptador — superficie completa de herramientas. Instala pi-mcp-adapter para exponer las herramientas MCP de Octocode detrás de una única herramienta proxy de ~200 tokens, de modo que los servidores permanezcan desconectados hasta que se llame a una herramienta. Habilita las herramientas de clonación con ENABLE_CLONE=true.

Bucle impulsado por investigación

La mayoría de los fallos de los agentes ocurren antes de la edición: adivinar quién controla un comportamiento, confiar en un fragmento sin leer la fuente, editar antes de probar el radio de impacto. Ejecuta un bucle más económico en su lugar: orienta con árboles, busca, lee evidencia exacta, usa AST/LSP cuando la identidad importe, luego parchea y verifica. El host edita, Octocode es el mapa, y los skills codifican el hábito.

El Manifiesto

"El código es la verdad, pero el contexto es el mapa." Lee el Manifiesto de Octocode para el Desarrollo Impulsado por Investigación para entender la filosofía detrás de Octocode.