Octocode — Evidence-First Code Research for AI Agents & Developers

# Octocode > Evidence-first code research for AI agents and developers. One engine, two interfaces: an MCP server (`octocode-mcp`) and the `npx octocode` CLI. 13 research tools across GitHub and local codebases — code search, AST and LSP navigation, pull-request history, npm lookup, and OQL — plus 1 installable agent skill. Open source, MIT, free. Octocode turns guess-driven work into research-driven work. The loop is always the same: orient → search → read exact evidence → prove. Every tool returns compact, citable results with built-in next-step hints. Token knobs keep output small — `concise` returns path-only lists; `minify` reads a file's shape (signature skeleton) instead of every byte. The same 13 tools run identically whether the agent calls them over MCP or runs the CLI. Local tools need no auth; GitHub tools use your token. ## Run Octocode via MCP Add the server to any MCP client, then ask the assistant to use Octocode. - Config (any host): `{"octocode":{"command":"npx","type":"stdio","args":["octocode-mcp@latest"]}}` - Claude Code: `claude mcp add-json octocode --scope user '{"command":"npx","type":"stdio","args":["octocode-mcp@latest"]}'` - Any client (auto-detect installed hosts): `npx octocode install` - Authenticate for GitHub / private repos: `npx octocode auth login`, then `npx octocode status` to verify the active token ## Run Octocode via CLI Same engine, no MCP client required. Local paths route to local tools; `owner/repo[/path]` routes to GitHub. - `npx octocode` — interactive research session - `npx octocode search <term> <path|owner/repo>` — text, regex, AST (`--pattern`), or full OQL (`--query`) - `npx octocode search <path|owner/repo> --tree` — browse a directory or repository tree - `npx octocode search <file>` — read file content (`--content-view exact|compact|symbols`) - `npx octocode search <file> --op definition|references|callers|callees|hover` — LSP navigation - `npx octocode search <…> --target reposi