# 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 8 installable agent skills. The same engine runs over an MCP server (octocode-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 (8 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. **Research** (`octocode-research`) ⭐ — Evidence-first investigation: investigate, implement, review, refactor, or audit across local code, GitHub, npm, PR history, binaries, and OQL. Loops from cheap discovery to cited structural proof.
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. **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.
4. **RFC Generator** (`octocode-rfc-generator`) — Turns evidence and alternatives into an RFC, design doc, architecture proposal, migration plan, or implementation plan with citations.
5. **Roast** (`octocode-roast`) — Sharp, evidence-backed code critique with file:line citations and fix paths. Secrets redacted, never personal.
6. **Skills** (`octocode-skills`) — Find, compare, evaluate, lint, rate, improve, install, or author Agent Skills (SKILL.md folders).
7. **Awareness** (`octocode-awareness`) — Memory, file locks, peer messages, and verified handoffs for concurrent agents on shared code. File-backed, no external deps.
8. **Stats** (`octocode-stats`) — Usage dashboard from ~/.octocode/stats.json: 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":["octocode-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
- **/mcp** — MCP server: 14 research tools, install guide, config, auth priority
- **/cli** — CLI: 13 commands, search flags, raw tool access
- **/skills** — 8 installable agent skills with install commands
- **/agent** — Pi harness: research engine, persistent memory, 7 bundled skills
- **/tools** — All 14 research tools with parameters and descriptions
- **/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/octocode-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/