# Octocode

> Evidence-first code research for AI agents and developers. One engine, two interfaces: an MCP server (`octocode-mcp`) and the `npx octocode` CLI. 14 research tools across GitHub and local codebases — code search, AST and LSP navigation, pull-request history, npm lookup, and OQL — plus 8 installable agent skills. 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 14 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 repositories|packages|pullRequests|commits|diff` — GitHub & npm
- `npx octocode skill --list | --name <skill>` — browse or install agent skills
- `npx octocode auth | status | tools | --help` — auth, introspection, full usage

## Tools (14)

GitHub:

- `ghSearchCode` — code and path search by owner, repo, path, filename, extension, match (1–5 parallel queries; knob: `concise`)
- `ghGetFileContent` — read a GitHub file or region: full file, line range, match slice, or paginated chars (knob: `minify`)
- `ghViewRepoStructure` — browse a repository directory tree before reading files
- `ghSearchRepos` — discover repositories by keyword, owner, topic, language, stars, forks, size, dates, license
- `ghHistoryResearch` — search pull-request history, or deep-read one PR (files, patches, comments, reviews, commits)
- `ghCloneRepo` — clone a repo or sparse subtree into the local cache for local + LSP analysis (opt-in: `ENABLE_CLONE=true`)

Local:

- `localSearchCode` — local code/text search; `mode:"structural"` runs AST shape queries (pattern or YAML rule)
- `localViewStructure` — browse a local directory tree: depth, filters, sorting, pagination, metadata
- `localFindFiles` — find 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, paginated (knob: `minify`)
- `localBinaryInspect` — inspect archives, compressed streams, and native binaries: format, symbols, imports, deps, extract, decompress, strings

Package, LSP, and OQL:

- `npmSearch` — npm package lookup and keyword search; returns metadata and the source repository for GitHub handoff
- `lspGetSemantics` — typed LSP navigation: definition, references, callers, callees, callHierarchy, hover, documentSymbols, typeDefinition, implementation, supertypes, subtypes, diagnostic
- `oqlSearch` — typed OQL queries across code, content, structure, files, semantics, repositories, packages, pull requests, commits, artifacts, diff, research, and graph

## Skills (8)

Installable agent behavior protocols (structured markdown). Install with `npx octocode skill --name <skill>`.

- `octocode-research` — ⭐ recommended: investigate, implement, review, refactor, or audit with exact evidence; loops from cheap discovery to cited structural proof
- `octocode` — quick-lookup router; picks MCP or the CLI for focused, evidence-driven research
- `octocode-brainstorming` — validate ideas and map prior art; outputs a decision brief (Build RFC / Prototype / Narrow / Park)
- `octocode-rfc-generator` — turn evidence and alternatives into an RFC, design doc, migration, or implementation plan
- `octocode-roast` — sharp, evidence-backed code critique with file:line citations and a concrete fix for each finding
- `octocode-skills` — find, evaluate, lint, install, or author Agent Skills (SKILL.md folders)
- `octocode-awareness` — memory, file locks, and verified handoffs for concurrent agents on shared code
- `octocode-stats` — usage dashboard from ~/.octocode/stats.json: tokens saved, cache hits, errors, rate limits

## Pi Agent Harness

Install `@octocodeai/pi-extension` to give Pi a research engine, persistent memory, 7 skills, and subagent coordination in one package.

- Install: `pi install npm:@octocodeai/pi-extension`
- Authenticate: `npx octocode auth login`
- Verify: `/octocode-status`
- Agent page: https://octocode.ai/agent

## References

- [MCP reference](https://github.com/bgauryy/octocode/blob/main/docs/OCTOCODE_MCP.md): startup lifecycle, tool catalog, session persistence
- [CLI reference](https://github.com/bgauryy/octocode/blob/main/docs/OCTOCODE_CLI.md): full command syntax, flags, exit codes
- [Tools reference](https://github.com/bgauryy/octocode/blob/main/docs/OCTOCODE_TOOLS.md): all 14 tools, field-level guidance, cross-tool workflows
- [Configuration](https://github.com/bgauryy/octocode/blob/main/docs/CONFIGURATION.md): env vars, .octocoderc, token priority, GitHub Enterprise
- [Security model](https://github.com/bgauryy/octocode/blob/main/docs/SECURITY.md): secret redaction, path and command safety
- [OQL reference](https://github.com/bgauryy/octocode/blob/main/docs/OCTOCODE_QUERY_LANGUAGE.md): Octocode Query Language
- [NPM — MCP server](https://www.npmjs.com/package/octocode-mcp)
- [NPM — CLI](https://www.npmjs.com/package/octocode)

## Site Pages

- [Home](https://octocode.ai/): product overview and quick install
- [MCP](https://octocode.ai/mcp): MCP server — install, 14 tools, config, auth
- [CLI](https://octocode.ai/cli): CLI — 13 commands, search flags, examples
- [Skills](https://octocode.ai/skills): all 8 agent skills with install commands
- [Agent](https://octocode.ai/agent): Pi harness — capabilities, 7 skills, setup commands
- [Installation](https://octocode.ai/installation): full setup guide with troubleshooting
- [Tools](https://octocode.ai/tools): detailed tool reference
- [Blog](https://octocode.ai/blog)
- [Tutorials](https://octocode.ai/tutorials)
- [Slides](https://octocode.ai/slides)
- [Skills marketplace](https://www.skills.sh/bgauryy/octocode-mcp)