Octocode: Research Driven Development for AI

Stop Guessing. Start Knowing.

Empower your AI assistant with the skills of a Senior Staff Engineer.

octocode.ai

---

Installation

Prerequisites: GitHub authentication required. See Authentication Setup.

Recommended: Octocode CLI

npx octocode-cli install

Interactive setup wizard with GitHub OAuth, MCP server installation, and skills marketplace. Pass --ide <ide> for non-interactive install (e.g. npx octocode-cli install --ide cursor).

Alternative Methods

One-Click Install (Cursor)

Manual MCP 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

---

MCP Server

The Octocode MCP Server connects your AI assistant to code:

• GitHub, GitLab & Bitbucket: Search repositories, find usage patterns, read implementations, explore PRs/MRs
• 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

react_vue_comparisson.mp4

---

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.

Package	Purpose
octocode-mcp	MCP server — 14 tools across GitHub/GitLab/Bitbucket, local FS, LSP
octocode-cli	CLI — installer, tool runner, skills marketplace
octocode-vscode	VS Code extension — GitHub OAuth + multi-editor MCP install
octocode-shared	Shared utilities — credentials, session, platform
octocode-security-utils	Standalone security utilities

---

Skills

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

Research & Code Analysis

Skill	What it does
Researcher	Code search & exploration — local LSP + external (GitHub, npm/PyPI)
Research	Multi-phase research with sessions, checkpoints, state persistence
Engineer	Understand, write, analyze, audit code — AST + LSP + dependency graph
Brainstorming	Idea validation grounded in evidence — GitHub, npm/PyPI, web in parallel
News	What's new in AI, dev tools, web platform, security, notable repos

Planning & Writing

Skill	What it does
Plan	Evidence-based planning: Understand > Research > Plan > Implement
RFC Generator	Formal technical decisions with alternatives, trade-offs, and recommendations
Doc Writer	6-phase pipeline producing 16+ validated docs
Prompt Optimizer	Turn weak prompts into enforceable agent protocols
Agentic Flow	Thinking framework for designing/reviewing MCP & multi-agent workflows

Review & Critique

Skill	What it does
PR Reviewer	PR & local code review across 7 domains with LSP flow tracing
Roast	Brutal code critique with file:line citations and severity levels

Build & Output

Skill	What it does
Slides	Polished multi-file HTML presentations via 6-phase design flow
Design	Dynamic DESIGN.md generator covering visual language, components, a11y
Chrome DevTools	CDP-level browser debugging: network, console, perf, DOM, screenshots

Tooling & Setup

Skill	What it does
Install	Interactive step-by-step Octocode installer for macOS and Windows
CLI	Run Octocode MCP tools from the terminal without wiring MCP
Search Skill	Find, evaluate, install, refactor Agent Skills (SKILL.md format)
Stats	Local HTML dashboard from Octocode MCP usage stats

octocode-skill.mp4

---

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 · GitLab · Bitbucket
• Configuration Reference
• Using octocode-mcp with Pi

Tool References

• GitHub, GitLab & Bitbucket 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.

---

_{Built with care for the AI Engineering Community}