Octocode

Evidence-first code research for AI agents and developers.

Octocode researchesyour local code and external code alike(GitHub repositories, PRs, npm) with one toolset: ripgrep + AST search, trees, precise reads, and LSP. Use it as aCLIorMCP server, backed by aRust enginefor fast, token-efficient results across single files or mega-repos.

- Quick start
- Why Octocode
- Built for research (benchmarks)
- Tools
- MCP
- CLI
- Configuration
- Authentication methods
- Security
- Language support
- Skills
- Architecture
- Documentation
- Troubleshooting
- Agent workflows

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

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

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 underenv(seeConfiguration).

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) {"

Agents code better from evidence than from guesses. Octocode researchestwo worlds with one flow, yourlocal codeandexternal codeon 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 theagent 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 theexact matched lines/region, withsmart paginationandout-of-the-box minificationso the model never over-fetches. Every result carriesnext-step hintsto 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 prebuiltRust 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 (seeSecurity).

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

ghListReleasesandghSearchDiscussionsneed two settings on MCP, not one:ENABLE_RELEASES=1orENABLE_DISCUSSIONS=1puts the tool in the catalog, andENABLE_TOOLS="ghListReleases,ghSearchDiscussions"registers it. Either setting alone leaves the tool unregistered, because both carryisDefault: falseand the MCP registration filter admits only default or explicitly allowlisted tools. The CLI needs only theENABLE_RELEASESandENABLE_DISCUSSIONSflags.ENABLE_LOCALandENABLE_CLONEaccepttrueor1;ENABLE_RELEASESandENABLE_DISCUSSIONSalso acceptyesandon. Flags:Configuration.

Full schemas, fields, and examples for every tool live indocs/OCTOCODE_TOOLS.md(linked underDocumentation).

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

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

Add a GitHub token and options underenv- seeAuthenticationandConfiguration.

Same research engine, no MCP client needed. Local paths route to local tools;owner/repo[/path]routes to GitHub. Authenticate once withnpx octocode auth login(seeAuthentication); runnpx octocode --helpfor full usage.

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

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

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

…