Octocode: Research Driven Development for AI

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), and -m direct only to point a client at a locally installed MCP binary.

{
  "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:

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

Benchmark Snapshot

Hermetic evals: 212/212 passing. For agent research, Octocode MCP is the best default: it wins the combined benchmark with 99/105 quality and 17,274 output tokens on the full 60-query remote sweep (89% less than raw gh).

Token benchmark (lower is better)

Quality benchmark (higher is better)

Token × Quality visual axis

X-axis = token savings vs raw gh (right is better). Y-axis = research quality score (up is better). Best overall is the upper-right quadrant.

Quality ↑
100 |                                                  ● Octocode MCP
 90 |                                                    99/105 quality
 80 |                                      ● Octocode CLI 89% token savings
 70 |                                        79/105 quality
 60 |
 50 |
 40 |
 30 |
 20 |
 10 |
  0 | ● raw gh
    +--------------------------------------------------------------→ Token savings
      0%               40%               80%              90%+
      baseline                          CLI 81%        MCP 89%

Best-by-scenario matrix

Local note: Octocode local tools win for structured evidence, metadata, targeted reads, PCRE2, and LSP (definition, references, call hierarchy). Octocode verbosity:"concise" is available for lossy broad probes; use compact/default for evidence. Details: Benchmark Suite.

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

💻 As a CLI

Install the octocode command globally with Homebrew and run all 14 tools straight from your terminal, no MCP wiring required:

brew install bgauryy/octocode/octocode    # → octocode v1.5.0

Or brew tap bgauryy/octocode && brew install octocode (short form), or run on demand with npx octocode-cli. Node is pulled in automatically. Run octocode login first for the GitHub-backed tools.

The CLI is both a setup wizard (install the MCP server + skills, manage GitHub auth, sync configs across editors) and a standalone tool runner (call any Octocode tool, pipe the JSON anywhere).

Commands

Top-level flags: --version/-v, --help/-h, --json/-j.

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

Quick start

octocode login                                   # GitHub OAuth
octocode install --ide cursor                    # wire MCP into an editor
octocode skills install --targets claude-code    # add Agent Skills
octocode tools                                    # list every tool
octocode tools localSearchCode --queries '{"path":".","pattern":"fn"}'

Install targets include Cursor, Claude Code, Claude Desktop, Windsurf, Zed, Trae, Antigravity, Kiro, Codex, Opencode, Gemini CLI, Goose, and the VS Code extensions Cline / Roo / Continue. Full details: 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.