Octocode

Octocode - Agentic Research Platform

Evidence-first code research for AI agents and developers.

Evidence from your local workspace and external sources (GitHub repos, PRs, npm). One toolset: ripgrep + AST search, trees, precise reads, and LSP — as a CLI or MCP server, backed by a Rust engine for fast, token-efficient results across single files or mega-repos.

Table of Contents

• Quick Start
• Why Octocode
• What You Can Do
• Tools
• MCP
• CLI
• Configuration
• Authentication Methods
• Security
• Language Support
• Skills
• Architecture
• Documentation
• Troubleshooting

Quick Start

1. Run the Octocode CLI with npx

npx octocode --help

2. Authenticate with GitHub — optional, but unlocks private repositories and higher API rate limits:

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

3. Choose your interface. The same engine and tools run identically either way.

🖥️ CLI — research straight from your terminal:

npx octocode

🤖 MCP — one-click install:

• <img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">
• <img src="https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white" alt="Install in VS Code">
• <img src="https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white" alt="Install in VS Code Insiders">
• <img src="https://img.shields.io/badge/Windsurf-Install_Server-1a1a1a?style=flat-square&logoColor=white" alt="Install in Windsurf">
• <img src="https://kiro.dev/images/add-to-kiro.svg" alt="Install in Kiro">
• <img src="https://goose-docs.ai/img/extension-install-dark.svg" alt="Install in Goose">
• <img src="https://files.lmstudio.ai/deeplink/mcp-install-light.svg" alt="Install in LM Studio">

Claude Code:

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

Any other client: npx octocode install

➡️ Learn more at octocode.ai.

Why Octocode

Agents write better code from evidence than from assumptions. Octocode turns guess-driven work into research-driven work. Before an agent changes, reviews, or explains code, it gathers real evidence from your local workspace and from GitHub repositories, pull requests, and npm packages, then hands it back as compact, citable context. Code is truth; context is the map.

Most tools cover one slice: searching the web, or grepping your repo. Octocode covers the whole research flow, end to end:

• Built for scale. In organizations with thousands of repositories and endless code, Octocode is the solution: spot a pattern in one repo, follow it through the pull request that introduced it, then trace the same shape across other repos and your own files without leaving the conversation. Clone any repo and study it locally, on any machine.
• Smart GitHub workflows. Parallel bulk queries and built-in next-step hints keep the agent on the cheapest path: search broadly, read narrowly, trace semantically. Each result points to the natural follow-up.
• No GitHub required. Even without GitHub, clone any repository locally and point Octocode's local tools (search, structural AST, LSP, content) at it for the same evidence-first research.
• Reads the shape, not the noise. Code is minified and skeletonized on the fly across 70+ languages, so an agent grasps a 100 KB file in a few hundred tokens instead of spending its context on boilerplate.
• Fast and self-contained. Search, parsing, semantic navigation, and redaction run in one prebuilt Rust engine: quick on a laptop or a mega-repo, with no extra toolchain to install.
• Safe by default. Every byte returned to the model is scanned and secrets redacted first (see Security).

What You Can Do

Octocode is useful whenever the next coding step depends on finding and proving context, not guessing it.

See Quick Start to install in your terminal or AI assistant.

Tools

13 always-on tools (same on MCP and CLI). Local tools on by default (ENABLE_LOCAL=false to disable). Three opt-ins: ghCloneRepo (MCP opt-in ENABLE_CLONE=true, CLI on by default), ghListReleases (ENABLE_RELEASES=true), and ghSearchDiscussions (ENABLE_DISCUSSIONS=true). Flags: Configuration.

Token knobs. concise:true returns path/title-only lists. minify controls file read density: symbols = skeleton with line numbers, standard = comments/blanks stripped (default), none = exact bytes.

GitHub Tools

Local Tools

Package Search

LSP

Full schemas, fields, and examples for every tool live in docs/OCTOCODE_TOOLS.md (linked under Documentation).

MCP

The MCP server exposes the Octocode tool catalog directly to your AI assistant over stdio.

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

Manual Configuration

Add to your MCP client config. Pick the package that matches the version you want:

New Octocode (Rust-powered engine) — use @octocodeai/mcp:

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

Classic octocode-mcp — use octocode-mcp:

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

Add a GitHub token and options under env — see Authentication and Configuration.

CLI

Same research engine, no MCP client needed. Local paths route to local tools; owner/repo[/path] routes to GitHub.

npx octocode auth login   # authenticate once
npx octocode status       # verify setup
npx octocode --help       # full usage

Commands

Tools

…