# Octocode

> Evidence-first code research for AI agents and developers. One engine, two interfaces: an MCP server (`@octocodeai/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 10 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":["@octocodeai/mcp@latest"]}}`
- Claude Code: `claude mcp add-json octocode --scope user '{"command":"npx","type":"stdio","args":["@octocodeai/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 (10)

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

- `octocode-engineer` — ⭐ recommended for code work: investigate, implement, review, refactor, or audit with exact evidence
- `octocode` — quick-lookup router; picks MCP or the CLI for focused, evidence-driven research
- `octocode-research` — evidence-first technical research and decision briefs (Map / Validate / Investigate / Plan)
- `octocode-loop` — Act → Observe → Learn loops until the evidence converges
- `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, or implementation plan
- `octocode-roast` — sharp, evidence-backed code critique with file:line citations and fix paths
- `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` — build a local dashboard of usage stats (tokens saved, cache hits, errors, rate limits)

## References

- [Full reference (llms-full.txt)](https://octocode.ai/llms-full.txt): tool specs, skills, FAQ, and install details
- [README](https://github.com/bgauryy/octocode/blob/main/README.md): quick start, tools, CLI, configuration
- [CLI reference](https://github.com/bgauryy/octocode/blob/main/docs/cli/REFERENCE.md): full command syntax, flags, exit codes
- [GitHub tools](https://github.com/bgauryy/octocode/blob/main/docs/mcp/tools/GITHUB_TOOLS.md)
- [Local tools](https://github.com/bgauryy/octocode/blob/main/docs/mcp/tools/LOCAL_TOOLS.md)
- [LSP tools](https://github.com/bgauryy/octocode/blob/main/docs/mcp/tools/LSP_TOOLS.md)
- [Binary tools](https://github.com/bgauryy/octocode/blob/main/docs/mcp/tools/BINARY_TOOLS.md)
- [Configuration](https://github.com/bgauryy/octocode/blob/main/docs/mcp/CONFIGURATION.md): env vars, `.octocoderc`, precedence
- [Authentication](https://github.com/bgauryy/octocode/blob/main/docs/AUTHENTICATION.md): tokens, gh CLI, OAuth, scopes
- [Security model](https://github.com/bgauryy/octocode/blob/main/docs/SECURITY.md): secret redaction, path and command safety
- [Skills index](https://github.com/bgauryy/octocode/blob/main/skills/README.md): all 10 skills, install guide
- [The Manifest (RDD)](https://github.com/bgauryy/octocode/blob/main/MANIFEST.md): research-driven development philosophy
- [NPM — MCP server](https://www.npmjs.com/package/@octocodeai/mcp)
- [NPM — CLI](https://www.npmjs.com/package/octocode)

## Optional

- [Website](https://octocode.ai): product overview and install
- [Tools page](https://octocode.ai/tools)
- [Skills page](https://octocode.ai/skills)
- [Installation](https://octocode.ai/installation)
- [Slides](https://octocode.ai/slides): talks and presentations
- [Tutorials](https://octocode.ai/tutorials)
- [Blog](https://octocode.ai/blog)
- [Skills marketplace](https://www.skills.sh/bgauryy/octocode-mcp)