Octocode: Research Driven Development for AI
Stop Guessing. Start Knowing.
Empower your AI assistant with the skills of a Senior Staff Engineer.
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):
- Correct Prompts: Auto-injects the Research Driven Development system prompts.
- Advanced Planning: Breaks down complex problems into specific research questions.
- Deep Research: Orchestrates the right MCP tools in the right order (e.g., Search → Go to Definition → Read).
- 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
One-Click Install (Cursor)
Manual Configuration
Add to your MCP configuration file:
{
"mcpServers": {
"octocode": {
"command": "npx",
"args": ["octocode-mcp@latest"]
}
}
}
Research Skill (Direct Install)
npx add-skill https://github.com/bgauryy/octocode-mcp/tree/main/skills/octocode-research