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

• octocode-mcp: The core MCP server for GitHub, Local FS, and LSP.
• octocode-cli: The command-line interface for managing Octocode.
• octocode-research: The Research Skill for autonomous RDD.
• octocode-vscode: VS Code extension for authentication.
• octocode-shared: Shared utilities and types.

🎥 Tutorials

• Octocode AI YouTube Channel - Video tutorials and deep dives.

🚀 Getting Started

• Installation Guide - Get started quickly. (See previous README sections below)
• Octocode CLI - The easiest way to install and manage skills.

📖 Core Concepts

• The Manifest - The philosophy behind RDD.

🛠️ Reference

• Authentication Setup - GitHub & GitLab authentication
• Configuration Reference - MCP server configuration options
• Troubleshooting - Common issues and solutions

---

Installation Guide

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

Quick Install

| Component | Command | Description | |-----------|---------|-------------| | MCP Server | npx octocode-cli | GitHub, Local FS & LSP tools for your AI | | Research Skill | npx add-skill octocode-research | Autonomous 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

---