Name: Octocode
Author: bgauryy

Octocode - Agentic Research Platform

</div>

Evidence-first code research for AI agents and developers.

Octocode gives an agent the full context it needs to change, review, or explain code: real evidence from your local workspace and from external sources (GitHub repositories, pull requests, and npm packages). One toolset covers all of it: ripgrep and AST structural search, repository tree browsing, precise content fetching, LSP semantic navigation, and binary inspection.

Run it as a CLI or an MCP server. A Rust engine keeps every call fast and token-efficient, minifying and skeletonizing code so an agent reads the shape of a file instead of every byte, from a single file to a mega-repo. It is also the best tool for cross-repository research and exploration across millions of repositories.

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

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 14 tools run identically either way.

🖥️ CLI — research straight from your terminal:

npx octocode

🤖 MCP — one-click install:

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.

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.
Binary or archive inspection	Inspect archives, compressed streams, native binaries, and strings without leaving the research flow.
Agent workflows	Expose the same engine through MCP, CLI, OQL, and Agent Skills so assistants and humans use one evidence model.

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

Tools

Octocode ships 14 research tools; the same implementations run identically over MCP and the CLI. Local tools are enabled by default; ENABLE_LOCAL=false disables them. ghCloneRepo is opt-in for MCP (ENABLE_CLONE=true) and enabled by default for CLI. All flags: Configuration Reference.

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, repo, 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.	`minify`
`ghViewRepoStructure`	Browse a GitHub repository's directory tree before reading files.
`ghSearchRepos`	Discover repositories by keywords, owner, topic, language, stars, forks, size, dates, license, visibility.	`concise`
`ghHistoryResearch`	Search PR history, or deep-read one PR: files, patches, comments, reviews, commits.	`concise`
`ghCloneRepo`	Clone a repo or sparse subtree into the local cache for local/LSP analysis. Opt-in (`ENABLE_CLONE=true`).	`sparsePath`

Local Tools

Tool	What it does	Knob
`localSearchCode`	Local code/text search returning file and line anchors. `mode:"structural"` runs Octocode AST shape queries (`pattern` or `rule`).	`mode`
`localViewStructure`	Browse a local directory tree: depth, filters, pagination, metadata.	`concise`
`localFindFiles`	Find local files and directories by name, path, regex, extension, size, time, permissions, type.
`localGetFileContent`	Read a local file or region: exact slice, match string, line range, or paginated chars.	`minify`
`localBinaryInspect`	Inspect archives, compressed streams, and native binaries: inspect (format/symbols/imports/deps), list, extract, decompress, strings.

Package Search

Tool	What it does	Knob
`npmSearch`	npm package lookup and keyword search; returns metadata and the source repository for GitHub handoff.	`concise`

LSP

Tool What it does

lspGetSemantics Typed semantic navigation. Raw tools support definition, references, callers, callees, callHierarchy, hover, documentSymbols, typeDefinition, implementation, workspaceSymbol, supertypes, subtypes, and diagnostic. The CLI uses npx octocode search <file> --op <type> for semantics and npx octocode search <file> --symbols for file or directory symbol outlines. Navigation runs through installed language servers (see the LSP Tools Reference).

OQL Search

Tool	What it does
`oqlSearch`	Runs typed OQL queries across code, content, structure, files, semantics, repositories, packages, pull requests, commits, artifacts, diff, research, graph, and materialization targets.

Full schemas, fields, and examples for every tool live in docs/mcp/tools (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:

{
  "octocode": {
    "command": "npx",
    "type": "stdio",
    "args": [
      "@octocodeai/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 onc

…

Octocode

Installation

Configuration

How to use

README