Octocode: Research Driven Development for AI

Research like a Senior Staff Engineer.
In every codebase, in seconds.

Stop guessing. Octocode researches code locally and externally: your own workspace (ripgrep + LSP-level go-to-definition, references, call hierarchy) and the world's (GitHub repos, PRs, npm/PyPI packages), turning it into verifiable evidence your AI can search, read, and trace.

Use it as an MCP server inside your AI assistant, or as a terminal CLI.

octocode.ai  ·  MCP Server  ·  CLI  ·  Skills

Two ways to run Octocode

Same engine, same tools, two surfaces. Pick one or use both.

Prerequisites: GitHub authentication for the GitHub-backed tools. Run octocode login, or see Authentication Setup.

🔌 As an MCP Server

Wire Octocode's tools into your AI assistant. The interactive installer handles GitHub OAuth, MCP server config, and the skills marketplace:

npx octocode-cli install

Pass --ide <client> for a non-interactive install (e.g. octocode install --ide cursor).

{
  "mcpServers": {
    "octocode": {
      "command": "npx",
      "args": ["octocode-mcp@latest"]
    }
  }
}

npx add-skill https://github.com/bgauryy/octocode-mcp/tree/main/skills/octocode-research

The Octocode MCP Server connects your AI assistant to code:

• GitHub: Search repositories, find usage patterns, read implementations, explore PRs
• Local Tools: Search code (ripgrep), browse directories, find files in your local codebase
• LSP Intelligence: Go to Definition, Find References, Call Hierarchy (compiler-level understanding)
• Package Discovery: Resolve npm/PyPI packages to their source repos

https://github.com/user-attachments/assets/de8d14c0-2ead-46ed-895e-09144c9b5071

💻 As a CLI

The same 14 tools, straight from your terminal — no MCP server, no IDE required.

Install

# Homebrew (macOS / Linux) — recommended
brew install bgauryy/octocode/octocode

# or tap once, then use the short name
brew tap bgauryy/octocode
brew install octocode

# npm global
npm install -g octocode-cli

# or run once, no install
npx octocode-cli install

Node is pulled in automatically by Homebrew. The installed command is octocode (not octocode-cli).

Verify and sign in:

octocode --version   # → octocode v1.5.3
octocode login       # GitHub OAuth — required for the GitHub-backed tools

What you get

The CLI is two things in one binary:

1. Setup wizard — install the MCP server + skills, manage GitHub OAuth, sync configs across 15 editors
2. Standalone tool runner — call any of the 14 tools, pipe JSON to other tools, use in CI

Commands

Top-level flags: --version/-v, --help/-h, --json/-j, --agent (agent bootstrap).

The 14 tools

Run any directly with octocode tools <name> --queries '<json>':

octocode tools                                                              # list all
octocode tools localSearchCode                                              # inspect schema
octocode tools localSearchCode --queries '{"path":".","pattern":"TODO"}'   # run
octocode tools githubSearchCode --queries '{"keywordsToSearch":["useState"],"owner":"facebook","repo":"react"}'

Supported install targets: Cursor, Claude Code, Claude Desktop, Windsurf, Zed, Trae, Antigravity, Kiro, Codex, Opencode, Gemini CLI, Goose, VS Code Cline / Roo / Continue. Full reference: CLI Reference.

Packages

This is a yarn-workspaces monorepo. Each package has its own README.md; all setup/reference docs live in docs/, and all AI agent guidance lives in the root AGENTS.md.

Skills

Agent Skills are a lightweight, open format for extending AI agent capabilities. Skills index: skills/README.md

Research & Code Analysis

Planning & Writing

Review & Critique

Build & Output

Tooling & Setup

https://github.com/user-attachments/assets/5b630763-2dee-4c2d-b5c1-6335396723ec

Documentation

Full index: docs/README.md. All monorepo documentation lives in docs/ (no per-package docs/).

Docs map

• docs/configuration/: install, auth providers, MCP clients, env/config, troubleshooting
• docs/dev/: tool/API references, workflows, architecture, contributing, skills
• docs/specs/: design specs and RFCs

Setup

• Authentication Setup · GitHub
• Configuration Reference
• Using octocode-mcp with Pi

Tool References

• GitHub Tools
• Local + LSP Tools
• Clone & Local Workflow

CLI & Skills

• CLI Reference
• Skills Guide · Skills Index
• CLI vs MCP Benchmark

Shared Internals

• Shared API Reference · Credentials Architecture · Session Persistence

Operations

• Troubleshooting · Development Guide · Agent Guidance (AGENTS.md)

The Manifest

"Code is Truth, but Context is the Map." Read the Manifest for Research Driven Development to understand the philosophy behind Octocode.

Contributing

See the Development Guide for monorepo setup, testing, and contribution guidelines.