Octocode

What is Octocode?

Octocode is an AI-powered code assistant designed to help developers understand and navigate complex codebases across GitHub and NPM. It provides advanced search capabilities with heuristic discovery and smart fallbacks to uncover connections between repositories and packages, regardless of privilege level.

How to use Octocode?

1. Install Prerequisites: Install Node.js (18.12+) and GitHub CLI.
2. Authenticate: Log in to GitHub using gh auth login and to NPM using npm login. Octocode leverages GitHub CLI's OAuth flow, eliminating the need for personal access tokens.
3. Add to MCP Configuration: Include octocode-mcp in your MCP configuration with the command npx octocode-mcp.

For developers, Octocode is also available as a Desktop Extension (DXT) for easy installation in AI applications like Claude Desktop. You can build the DXT package locally by cloning the repository, installing dependencies, and running yarn dxt:pack.

Key Features of Octocode

• AI-Powered Intelligence: Advanced search with heuristic pattern recognition, connection mapping between NPM packages and GitHub repositories, cross-reference analysis, progressive refinement, and context-aware discovery.
• Commit SHA Integration: Allows viewing files from specific commits and pull requests, analyzing PR code, and comparing code evolution across versions.
• Performance Optimization: Smart content selection, advanced minification, partial file access, and token efficiency (80-90% reduction in LLM token usage).
• Local-First Architecture: Runs entirely on your machine with zero data collection and no token management.
• Command Execution Security: Employs allowlisted commands, argument sanitization, pre-execution validation, and timeout protection.
• Comprehensive Toolset: Utilizes 10 specialized tools for discovery (Repository Search, Package Search), analysis (Code Search, Package Analysis, Repository Structure), activity (Commit Search, Pull Request Search, Issue Search), and content (File Content Fetching, API Status Check).

Use Cases of Octocode

Octocode can be used for various code exploration and research tasks, including:

• Understanding how specific features are implemented (e.g., "How did React implement concurrent rendering?").
• Discovering authentication patterns in applications (e.g., "Show me authentication patterns in Next.js applications").
• Finding examples of API usage.
• Analyzing the architecture of a library.
• Learning how to effectively use MCP tools.
• Generating tutorials for implementing specific functionalities (e.g., "Show implementations of langgraph in node js. Make a tutorial for how to implement a simple agent using OpenAI API.").
• Comparing different technologies (e.g., "How did React implement their concurrent rendering flows? How is it different from Vue.js rendering mechanism? Which is better?").

Octocode FAQ

• Q: What if I get no results?
  • A: Try broader search terms.
• Q: Why are private repositories not found?
  • A: Check your gh auth status for organization membership.
• Q: Is Octocode compatible with Windows?
  • A: Yes, PowerShell is automatically supported.
• Q: How does Octocode handle security and privacy?
  • A: It has a local-first architecture with no data collection, uses GitHub CLI for authentication (no personal access tokens), and employs robust command execution security measures like allowlisted commands and argument sanitization.

Octocode MCP

The Perfect AI Code Assistant - Advanced Search & Discovery Across GitHub & NPM

What is Octocode? 🐙

For more details, visit octocode.ai

The perfect code assistant that can help understand anything. Octocode provides AI-powered advanced search with heuristic discovery and smart fallbacks to understand connections between repositories and NPM packages across any privilege level you have.

Instead of manually browsing repositories, ask questions like:

• "How did React implement concurrent rendering?"
• "Show me authentication patterns in Next.js applications"
• "Find examples of how to use this specific API"
• "What's the architecture of this library?"
• "How do I use this MCP tool effectively?"

Unique Value Proposition

The most advanced AI-powered code assistant for understanding connections across the entire GitHub & NPM ecosystem. While other GitHub MCPs focus on project management or basic operations, Octocode provides unparalleled depth for code discovery and technical research.

Key Differentiators:

• 🧠 AI-Powered Search - Heuristic algorithms with smart fallbacks that understand code context and find relevant code even with vague queries
• 🔐 Zero-Config Security - Uses GitHub CLI authentication - no personal access tokens needed
• 🔗 Connection Intelligence - Maps NPM packages to repositories, traces dependencies, finds related implementations
• 🌐 Universal Access - Works seamlessly with public, private, and organization repositories
• ⚡ LLM Optimized - Advanced content minification and partial fetching reduces token usage by 80-90%

Quick Start 🚀

1. Install Prerequisites

# Install Node.js 18.12+
brew install node  # macOS
# or download from https://nodejs.org/

# Install GitHub CLI
brew install gh    # macOS
# or see: https://github.com/cli/cli#installation

2. Authenticate

# Login to GitHub (opens browser)
gh auth login

# Login to NPM (for package research)
npm login

🔐 Authentication Benefits:

• ✅ No personal access tokens - Uses GitHub CLI OAuth flow
• ✅ Enterprise ready - Works with SSO, 2FA, and organization access
• ✅ Automatic organization detection - Instantly accesses your private repositories
• ✅ Zero configuration - Uses existing gh CLI permissions

3. Add to MCP Configuration

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

That's it! Octocode automatically works with your organization's private repositories.

DXT Extension 📦

This project is available as a Desktop Extension (DXT) for easy installation in AI applications like Claude Desktop.

For Developers

Building the DXT Package:

# Install dependencies
yarn install

# Build the DXT package
yarn dxt:pack

# Validate the manifest
yarn dxt:validate

# View package information
yarn dxt:info

# Sign the package (optional)
yarn dxt:sign

DXT Scripts:

• yarn dxt:validate - Validate the manifest.json file
• yarn dxt:pack - Build and package the extension as a .dxt file
• yarn dxt:info - Show information about the packaged extension
• yarn dxt:sign - Sign the package with a self-signed certificate
• yarn dxt:verify - Verify the signature of a signed package

The DXT package includes:

• Compiled MCP server (dist/index.js)
• Extension manifest (manifest.json)
• Package metadata (package.json)
• Logo and assets (assets/logo.png)
• Documentation (README.md)

Building DXT from Source: To build the DXT package locally from this repository:

# Clone the repository
git clone https://github.com/bgauryy/octocode-mcp.git
cd octocode-mcp

# Install dependencies and build
yarn install
yarn build
yarn dxt:pack

The generated octocode-mcp.dxt file can then be installed in Claude Desktop (just click on it and it will open claude desktop with the extension)

How It Works 🔄

Smart Discovery Flow:

1. 🔍 Query Analysis → AI determines the best search strategy
2. ⚡ Multi-Tool Orchestration → Intelligently combines 10 specialized tools
3. 🔄 Smart Fallbacks → Automatically retries with different approaches
4. 🔗 Cross-Reference Discovery → Links packages to repositories with commit SHA integration
5. 🎯 Context Synthesis → Provides comprehensive understanding

Example Flows

Example 1: LangGraph Node.js Implementation Tutorial

Query: "Show implementations of langgraph in node js. Make a tutorial for how to implement a simple agent using OpenAI API."

Example 2: Zustand React State Management

Query: "Show me how to add zustand to react application. Show examples and best practices"

Example 3: React vs Vue.js Rendering Comparison

Query: "How did React implement their concurrent rendering flows? How is it different from Vue.js rendering mechanism? Which is better?"

Core Features 🛠️

🧠 AI-Powered Intelligence

• Advanced Search - Heuristic pattern recognition with automatic fallback strategies
• Connection Mapping - Automatically links NPM packages to GitHub repositories
• Cross-Reference Analysis - Discovers how different projects implement similar patterns
• Progressive Refinement - AI-guided search that improves with each iteration
• Context-Aware Discovery - Understands relationships between code, commits, issues, and discussions

🔗 Commit SHA Integration

• Time Travel Code Viewing - View files from specific commits and pull requests
• PR Code Analysis - Automatically fetch commit SHAs for precise code comparison
• Historical Implementation - Compare code evolution across versions

⚡ Performance Optimization

• Smart Content Selection - Extracts only relevant code sections
• Advanced Minification - Language-aware compression preserving meaning
• Partial File Access - Fetches targeted line ranges
• Token Efficiency - 80-90% reduction in LLM token usage

Available Tools

10 specialized tools working together intelligently:

Discovery: Repository Search, Package Search
Analysis: Code Search, Package Analysis, Repository Structure
Activity: Commit Search, Pull Request Search, Issue Search
Content: File Content Fetching, API Status Check

All tools feature automatic cross-referencing and intelligent fallbacks.

Security & Privacy 🛡️

Local-First Architecture

• 🏠 100% Local - Runs entirely on your machine
• 🚫 Zero Data Collection - No telemetry or data transmission
• 🔑 No Token Management - Uses GitHub CLI authentication

Command Execution Security

• ⚪ Allowlisted Commands Only - Pre-approved safe commands
• 🛡️ Argument Sanitization - Prevents shell injection attacks
• ✅ Pre-execution Validation - Every command is validated
• 🔧 Controlled Environment - Cross-platform secure shell execution
• ⏱️ Timeout Protection - Prevents resource exhaustion

Best Practices 💡

Effective Questions:

• Start with natural language - "How does authentication work?"
• Ask for connections - "What libraries use this pattern?"
• Cross-ecosystem queries - "NPM packages that implement X"
• Evolution questions - "How has this approach changed?"

Pro Tips:

• Let AI guide discovery - vague queries work great
• Trust smart fallbacks - automatic retry with alternatives
• Build on previous searches - maintain context for deeper exploration
• Works everywhere - public, private, and organization repositories

Troubleshooting 🔧

# Check GitHub CLI status
gh auth status

# Re-authenticate if needed
gh auth logout && gh auth login

# Check NPM access
npm whoami

# Clear NPX cache if needed
rm -rf ~/.npm/_npx

Common Solutions:

• No results? Try broader search terms
• Private repos not found? Check gh auth status for organization membership
• Windows users? PowerShell is automatically supported

Background 💭

This project started as a personal tool while working at Wix, born from the challenge of navigating large codebases and keeping up with rapidly evolving technology landscapes. What began as a side project evolved into the perfect code assistant that can help understand anything.

The goal: make code exploration as intelligent as having a senior developer guide you through any codebase.

License 📄

MIT License - See LICENSE for details.

---