Octocode MCP

A server for semantic code search and context generation across public and private repositories using LLMs.

GitHub

Octocode: Research Driven Development for AI

Octocode is not just a tool; it's a methodology and a platform that transforms how AI interacts with code. It moves AI from "guessing" based on training data to "knowing" based on deep, evidence-based research.

This repository contains the complete ecosystem that powers this transformation.

📜 The Manifest

"Code is Truth, but Context is the Map."

At the heart of Octocode lies the Manifest for Research Driven Development (RDD).

👉 Read the full manifest here: MANIFEST.md

The Manifest defines a new philosophy for AI coding:

  • Vibe-Research: Enabling AI to intuitively explore code like a human.
  • Evidence First: No line of code is written without proof it's needed and correct.
  • Adversarial Validation: AI agents check each other's work (Planner vs. Verifier) to ensure quality.

It answers the question: How can we trust AI to build complex software? By forcing it to research before it acts.

🔌 The MCP (Model Context Protocol)

The Eyes and Hands of Octocode.

The Octocode MCP Server (packages/octocode-mcp) is the bridge between your AI (like Claude or Cursor) and the world of code. It acts as the engine that powers the research.

  • GitHub Tools: Search millions of repositories, find usage patterns, and read real-world implementations.
  • Local Tools: Explore your local codebase with filesystem access.
  • LSP Intelligence: "Go to Definition", "Find References", and "Call Hierarchy" — giving AI the semantic understanding of a compiler.

The MCP Server provides the capabilities to see, touch, and understand code structure.

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

🧠 The Skill

The Brain of the Operation.

Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows.

Octocode is supported in both MCP and as a skill!

It adds specialized capabilities out-of-the-box (OOTB):

  1. Correct Prompts: Auto-injects the Research Driven Development system prompts.
  2. Advanced Planning: Breaks down complex problems into specific research questions.
  3. Deep Research: Orchestrates the right MCP tools in the right order (e.g., Search → Go to Definition → Read).
  4. Parallel Agents: Handles spawning sub-agents for parallel execution of research tasks.

This skill turns a generic AI model into a specialized Research Architect.

💡 Tip: Ask Octocode to "roast your code" and you will get a surprise! 🔥🎭

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

⌨️ The CLI

Your Command Center.

Octocode comes with a powerful CLI to manage your agent's capabilities.

npx octocode-cli

It handles:

  • Authentication: Easy GitHub OAuth setup.
  • Installations: One-click setup for MCP servers and Skills.
  • Management: Interactive menu for all Octocode features.

📚 Documentation

Everything you need to master Octocode:

📦 Packages in this Monorepo

🎥 Tutorials

🚀 Getting Started

📖 Core Concepts

🛠️ Reference

Installation Guide

Prerequisites: GitHub authentication is required for all installations.
See Authentication Setup for details.

Quick Install

ComponentCommandDescription
MCP Servernpx octocode-cliGitHub, Local FS & LSP tools for your AI
Research Skillnpx add-skill octocode-researchAutonomous research agent capabilities

Recommended: Octocode CLI

The CLI is the easiest way to install and manage everything:

npx octocode-cli

Features:

  • Interactive setup wizard
  • GitHub OAuth authentication
  • MCP server installation
  • Skills marketplace

Alternative Installation Methods

Add to your MCP configuration file:

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

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

Related Servers