# Octocode — Complete Reference for AI Assistants

> Octocode is evidence-first code research for AI agents and developers. It gives AI assistants (Cursor, Claude, VS Code, Windsurf) deep access to GitHub and local codebases through 14 research tools and 10 installable agent skills. The same engine runs over an MCP server (@octocodeai/mcp) and the npx octocode CLI. Open source, MIT licensed, free to use.

## What Octocode Does

Octocode connects to your AI assistant via the Model Context Protocol (MCP), or runs straight from the terminal as the `npx octocode` CLI. Both are thin front-ends over one shared tool core, which delegates CPU-heavy work to a single prebuilt Rust engine (secret scanning, minification, signatures, structural AST, ripgrep/diff/YAML, LSP). It provides 14 research tools in five groups:

### GitHub Tools (6)
- **ghSearchCode** — Code and path search across GitHub by owner, repo, path, filename, extension, and match filters. Accepts 1 to 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. Auto-filters noisy paths.
- **ghSearchRepos** — Discover repositories by keywords, owner, topic, language, stars, forks, size, dates, license, and visibility. Knob: `concise`.
- **ghHistoryResearch** — Search pull-request history, or deep-read one PR: files, patches, comments, reviews, and commits.
- **ghCloneRepo** — Clone a repo or sparse subtree into the local cache for local/LSP analysis. Opt-in for MCP (`ENABLE_CLONE=true`), default-on for the CLI.

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

### Package Search (1)
- **npmSearch** — npm package lookup and keyword search. Returns metadata and the source repository so research can continue on GitHub.

### LSP (1)
- **lspGetSemantics** — Typed semantic navigation through installed language servers: definition, references, callers, callees, callHierarchy, hover, documentSymbols, typeDefinition, implementation, supertypes, subtypes, and diagnostic. JS/TS also have a native, no-server path.

### OQL (1)
- **oqlSearch** — Run typed OQL queries across code, content, structure, files, semantics, repositories, packages, pull requests, commits, artifacts, diff, research, graph, and materialization targets.

### How Tools Connect — The Research Loop

Octocode follows an evidence-first loop:

1. **Orient** (ghViewRepoStructure, localViewStructure, localFindFiles) — Map the tree and locate relevant files before reading.
2. **Search** (ghSearchCode, localSearchCode, npmSearch) — Find patterns, symbols, and packages. Carry path/line anchors forward.
3. **Analyze** (lspGetSemantics, localSearchCode structural) — Resolve definitions, references, and call hierarchy when identity matters.
4. **Prove** (ghGetFileContent, localGetFileContent, ghHistoryResearch) — Read exact regions and PR history to prove the answer with citations.

Token knobs keep results small (`concise` for path-only lists, `minify` to read a file's shape), and every result carries built-in next-step hints.

## Skills (10 Installable Agent Behaviors)

Skills are structured markdown protocols that encode the workflows agents should follow. Install any skill with `npx octocode skill --name <skill-name>`, or browse on skills.sh/bgauryy/octocode-mcp.

1. **octocode-engineer** ⭐ (`octocode-engineer`) — Architecture-aware investigation and code change. Investigate, implement, review, refactor, or audit local and remote code with exact evidence. Flow: PROBE → ROUTE → MAP → PROVE → CHANGE.
2. **Octocode** (`octocode`) — The quick-lookup router. Picks MCP or the CLI, then runs focused, evidence-driven research: local and GitHub search, exact reads, npm, PRs, history. Flow: ORIENT → SEARCH → READ → PROVE.
3. **Research** (`octocode-research`) — Evidence-first technical research and decision briefs across local code, GitHub, npm, PR history, binaries, and OQL. Modes: Map / Validate / Investigate / Plan.
4. **Loop** (`octocode-loop`) — Closed-loop research where each tool result steers the next call until evidence converges or a budget stops it. Flow: FRAME → ACT → OBSERVE → LEARN → REPEAT.
5. **Brainstorming** (`octocode-brainstorming`) — Evidence-grounded idea validation and white-space mapping. Diverge, then converge on real data. Outputs a decision brief: Build RFC / Prototype / Narrow / Park.
6. **RFC Generator** (`octocode-rfc-generator`) — Turns evidence and alternatives into an RFC, design doc, architecture proposal, migration plan, or implementation plan with citations.
7. **Roast** (`octocode-roast`) — Sharp, evidence-backed code critique with file:line citations and fix paths. Six severity levels, secrets redacted, never personal.
8. **Skills** (`octocode-skills`) — Find, compare, evaluate, lint, rate, improve, install, or author Agent Skills (SKILL.md folders).
9. **Awareness** (`octocode-awareness`) — Memory, file locks, peer messages, and verified handoffs for concurrent agents on shared code. File-backed, no external deps.
10. **Stats** (`octocode-stats`) — Builds a local dashboard from Octocode usage stats: tokens/chars saved, cache hits, tool-call counts, errors, and rate limits.

## Installation

### Quick Start (under 2 minutes)
1. **Authenticate**: `npx octocode auth login` (then `npx octocode status` to verify), or `gh auth login`
2. **Install in Cursor**: Use the one-click install link at https://octocode.ai/installation
3. **Install in Claude Code**: `claude mcp add-json octocode --scope user '{"command":"npx","type":"stdio","args":["@octocodeai/mcp@latest"]}'`
4. **Install in VS Code**: Use the one-click install link at https://octocode.ai/installation
5. **Any other client**: `npx octocode install`
6. **Or skip MCP**: just run `npx octocode`

### Requirements
- Node.js v20.0.0 or higher
- GitHub account or token (for GitHub features; local tools need no auth)
- An MCP-compatible AI assistant, or just a terminal for the CLI

## Why Octocode — Key Differentiators

- **Evidence-first** — Orient → Search → Read exact evidence → Prove. Snippets are leads; cited source is proof.
- **One engine, two interfaces** — The same 14 tools run over an MCP server and the npx octocode CLI.
- **LSP compiler-accurate navigation** — Real language server definitions, references, and call hierarchy, plus structural AST search across 60+ languages.
- **Reads the shape, not the noise** — On-the-fly minification and signature skeletons keep large files cheap to read.
- **Secure by default** — Read-only, 300+ secret patterns redacted on input and output, sensitive files blocked, path and command guardrails.
- **Free and open source** — MIT license. No signup or API key needed for local tools.

## Website Structure

- **/** — Home: product overview, quick install, social proof
- **/installation** — Setup for Cursor, Claude Code, VS Code, Windsurf, and the CLI
- **/tools** — All 14 research tools with parameters and descriptions
- **/skills** — 10 installable agent skills
- **/tutorials** — Video walkthroughs and examples
- **/blog** — Articles on MCP, code research, and AI-assisted development
- **/blog/:slug** — Individual blog posts

## Links
- Website: https://octocode.ai
- GitHub: https://github.com/bgauryy/octocode
- NPM (MCP): https://www.npmjs.com/package/@octocodeai/mcp
- NPM (CLI): https://www.npmjs.com/package/octocode
- Installation: https://octocode.ai/installation
- Tools Reference: https://octocode.ai/tools
- Skills: https://octocode.ai/skills
- Tutorials: https://octocode.ai/tutorials
- Blog: https://octocode.ai/blog

## FAQ

**Q: Is Octocode free?**
A: Yes. Octocode is open source under the MIT license and completely free.

**Q: What AI assistants does Octocode work with?**
A: Cursor, Claude Code, VS Code, Windsurf, and any MCP-compatible client. You can also run it from the terminal with `npx octocode` — no MCP client required.

**Q: Do I have to use MCP?**
A: No. The same research engine and 14 tools are available as the `npx octocode` CLI. Local paths route to local tools; `owner/repo` routes to GitHub.

**Q: Does Octocode access my private repositories?**
A: Only if you authenticate with GitHub. Octocode uses your existing credentials and respects repository access permissions.

**Q: Is Octocode read-only?**
A: Yes, by default. Octocode is designed for research — it reads and analyzes code but does not modify it.

**Q: How is Octocode different from GitHub's official MCP server?**
A: Octocode adds local codebase analysis, LSP semantic navigation, structural AST search, on-the-fly minification, a research CLI, installable agent skills, and an evidence-first research loop. See the comparison at https://octocode.ai/blog/mcp-explained-comparison-code-search-mcps

**Q: What is the difference between Tools and Skills?**
A: **Tools** (14) are the research API surface — individual functions that search, navigate, read, and inspect code. **Skills** (10) are installable agent behavior protocols (structured markdown) that encode the workflows agents should follow before and while they use those tools.

## Author
Guy Bary — https://x.com/guy_bary — https://www.linkedin.com/in/bgauryy/