Octocode: agentic research platform

<div align="center"> <img src="https://github.com/bgauryy/octocode/raw/main/packages/octocode-mcp/assets/logo_white.png" width="400px" alt="Octocode Logo">

</div>

Evidence-first code research for AI agents and developers.

Octocode researches your local code and external code alike (GitHub repositories, PRs, npm) with one toolset: ripgrep + AST search, trees, precise reads, and LSP. Use it 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
• Built for research (benchmarks)
• Tools
• MCP
• CLI
• Configuration
• Authentication methods
• Security
• Language support
• Skills
• Architecture
• Documentation
• Troubleshooting
• Agent workflows

---

Quick start

Prerequisites: Node.js 20.12+

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. Same tools and Rust engine on both. (Clone is on by default in the CLI, opt-in for MCP.)

🖥️ 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">

<details> <summary><b>Show more install options (Windsurf, Kiro, Goose, LM Studio, Claude Code)</b></summary> <br>

• <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":["octocode-mcp@latest"]}'

</details>

Any other client: npx octocode install

---

Use it as an MCP server

Add to your MCP client config (or use a one-click install above):

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

Put a GitHub token and options under env (see Configuration).

Use it as an agentic-friendly CLI

Run npx octocode and agents figure out the rest. The bare command prints built-in usage and the full tool catalog, so any coding agent knows how to drive it out of the box, no MCP client or extra wiring required.

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

Every MCP tool is also a plain command: JSON in, token-efficient YAML out. Local paths route to local tools; owner/repo[/path] routes to 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) {"

Learn more at octocode.ai.

---

Why Octocode

Agents code better from evidence than from guesses. Octocode researches two worlds with one flow, your local code and external code on GitHub and npm, and hands back compact, citable context before an agent changes, reviews, or explains code. Code is truth; context is the map.

Most tools do one slice (web search, or grep your repository) and hand back a fixed blob. Octocode covers the whole loop and lets the agent decide what data it needs next:

• Agent-driven, efficient flows. Instead of one-shot dumps, Octocode chains cheap steps into an optimized research flow: broad code search, then fetch only the exact matched lines/region, with smart pagination and out-of-the-box minification so the model never over-fetches. Every result carries next-step hints to the cheapest follow-up.
• Scales to monorepos. Spot a pattern in one repository, follow the PR that introduced it, then trace it across other repositories and your own files, without leaving the chat. Clone any repository and study it locally.
• Smart GitHub flow. Parallel bulk queries across code, PRs, commits, issues, and repositories, all with the same search-broad, read-narrow, trace-semantically discipline.
• Works without GitHub. Clone any repository and point the local tools (search, AST, LSP, content) at it, same evidence-first flow.
• Reads shape, not noise. On-the-fly minify/skeletonize across 70+ languages: a 100 KB file in a few hundred tokens, not walls of boilerplate.
• Fast, self-contained. Search, parsing, navigation, and redaction run in one prebuilt Rust engine: quick on a laptop or a mega-repo, nothing extra to install.
• Safe by default. Every byte to the model is scanned and secrets redacted first (see Security).

What you can do (whenever the next step needs proven context, not a guess):

| Need | Use Octocode to | |------|-----------------| | Codebase questions | Search local or GitHub code, read exact regions, browse trees, and carry file/line anchors into the answer. | | Implementation research | Compare patterns across repositories, npm packages, pull requests, commits, and local files before changing code. | | Semantic navigation | Resolve definitions, references, callers/callees, call hierarchy, hovers, symbols, diagnostics, and type relationships through LSP. | | Structural matching | Run AST-shaped searches with patterns or YAML rules so comments and strings do not become false positives. | | Large-file context | Minify, skeletonize, or paginate code so agents spend tokens on relevant structure instead of boilerplate. | | Agent workflows | Same engine through MCP, CLI, and Agent Skills. |

---

Built for research (benchmarks)

A blind, head-to-head test on research-oriented flows rather than plain lookups (multi-hop traces, dependency/call-graph chains, commit ranges, blast-radius, PR reviews across repositories).

How it works: 30 GitHub questions × 3 passes; Octocode vs gh, gh+Headroom, and gh+RTK on identical questions (only the CLI differs). A blind judge (gpt-5.5) grades correctness; the metric is characters through the model, counted from instrumented logs (characters, not tokens). Result: at near-parity correctness, Octocode answers with ~2.0× fewer characters than plain gh, ~2.6× fewer than gh+Headroom, and ~3.2× fewer than gh+RTK in the local-build headline runs.

▶ Open the interactive report · run it / method · questions · all reports

---

Tools

17 tools in the full catalog. How many register depends on the surface and the flags you set:

| Surface | Registers | What that set is | |---|---:|---| | MCP, no flags | 8 | GitHub search and read, plus npmSearch | | MCP, ENABLE_LOCAL=true | 14 | Adds the five local tools and lspGetSemantics | | MCP, + ENABLE_CLONE=true | 15 | Adds ghCloneRepo | | MCP, + ENABLE_TOOLS allowlist | 17 | Adds ghListReleases and ghSearchDiscussions | | CLI, no flags | 15 | Local tools and clone are on by default | | CLI, + ENABLE_RELEASES=1 ENABLE_DISCUSSIONS=1 | 17 | Adds the same two GitHub tools |

ghListReleases and ghSearchDiscussions need two settings on MCP, not one: ENABLE_RELEASES=1 or ENABLE_DISCUSSIONS=1 puts the tool in the catalog, and ENABLE_TOOLS="ghListReleases,ghSearchDiscussions" registers it. Either setting alone leaves the tool unregistered, because both carry isDefault: false and the MCP registration filter admits only default or explicitly allowlisted tools. The CLI needs only the ENABLE_RELEASES and ENABLE_DISCUSSIONS flags. ENABLE_LOCAL and ENABLE_CLONE accept true or 1; ENABLE_RELEASES and ENABLE_DISCUSSIONS also accept yes and on. 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

| Tool | What it does | Knob | |------|--------------|------| | ghSearchCode | Code and path search across GitHub by owner, repository, path, filename, extension, and match filters. Accepts 1 to 5 parallel queries. | concise | | ghGetFileContent | Read a GitHub file or region: full file, line range, match slice, or paginated chars. |