Octocode

AI-Powered Code Intelligence with Built-in MCP Server

Transform your codebase into a queryable knowledge graph. Ask questions in plain English, get precise answers.

🚀 Quick Start • 📖 Documentation • 🔌 MCP Server • 🌐 Website

---

🤔 Why Octocode?

You know that feeling — staring at a 100k+ line codebase, trying to find where authentication is handled, or how the database layer connects to the API. Traditional search (grep, ripgrep) only finds exact matches. Octocode understands meaning.

# Instead of this:
grep -r "auth" --include="*.rs" | head -20  # 847 results, mostly noise

# Do this:
octocode search "how is user authentication implemented"
# → 3 relevant files with context and relationships

Octocode builds a semantic knowledge graph of your entire codebase using tree-sitter AST parsing and vector embeddings. It connects your code to AI assistants via the Model Context Protocol (MCP) — giving Claude, Cursor, and other AI tools deep contextual understanding of your project.

✨ What Makes It Different

Feature	Traditional Search	Octocode
Query style	Exact keywords	Natural language
Results	Text matches	Semantic meaning + relationships
Context	Single file	Cross-file dependencies & imports
AI integration	None	Native MCP server + LSP
Speed	Instant	<2s indexing, instant queries

Built with Rust for performance. Local-first for privacy. Open source (Apache 2.0) for transparency.

🚀 Quick Start

1. Install (30 seconds)

# Universal installer (Linux, macOS, Windows)
curl -fsSL https://raw.githubusercontent.com/Muvon/octocode/master/install.sh | sh

# Or with Cargo
cargo install --git https://github.com/Muvon/octocode

2. Configure API Keys (1 minute)

# Required: Voyage AI (200M free tokens/month)
export VOYAGE_API_KEY="your-voyage-api-key"

# Optional: OpenRouter (for AI commit messages, code review)
export OPENROUTER_API_KEY="your-openrouter-api-key"

Get Voyage AI key • Get OpenRouter key

3. Index Your Codebase (2-5 minutes)

cd /your/project
octocode index
# → Indexed 12,847 blocks across 342 files

4. Search with Natural Language

# Single query
octocode search "HTTP middleware pattern"

# Multi-query for comprehensive results
octocode search "authentication" "middleware" "session"

# With filters
octocode search "database connection pool" --lang rust

5. Connect AI Assistants (MCP Server)

# Start MCP server for Claude Desktop, Cursor, etc.
octocode mcp --path /your/project

# Or HTTP mode for custom integrations
octocode mcp --bind 0.0.0.0:12345

🔌 MCP Server Integration

Octocode includes a built-in MCP server that exposes your codebase as tools to AI assistants:

Tool	What It Does
search_code	Semantic search across your entire codebase
get_file_context	Retrieve specific files with surrounding context
query_graph	Ask questions about code relationships and dependencies
get_symbols	Find functions, structs, classes by name or purpose

Works with: Claude Desktop • Cursor • Any MCP-compatible client

See MCP Integration Guide for setup instructions.

🎯 Use Cases

• 🆕 Onboarding — "How does the auth system work?" → Get the full picture in seconds
• 🔍 Code Archaeology — Find legacy code patterns without knowing exact names
• 🤖 AI Pair Programming — Give your AI assistant complete codebase context
• 📝 Refactoring — Understand dependencies before making changes
• 🔎 Code Review — "Show me all error handling in the API layer"

🌐 Supported Languages

Language	Extensions	Features
Rust	.rs	Full AST parsing, pub/use detection, module structure
Python	.py	Import/class/function extraction, docstring parsing
TypeScript/JavaScript	.ts, .tsx, .js, .jsx	ES6 imports/exports, type definitions
Go	.go	Package/import analysis, struct/interface parsing
PHP	.php	Class/function extraction, namespace support
C++	.cpp, .hpp, .h	Include analysis, class/function extraction
Ruby	.rb	Class/module extraction, method definitions
Java	.java	Import analysis, class/method extraction
JSON	.json	Structure analysis, key extraction
Bash	.sh, .bash	Function and variable extraction
Markdown	.md	Document section indexing, header extraction

Plus: CSS, Lua, Svelte, and more via tree-sitter

📚 Documentation

• Getting Started — First steps and basic workflow
• Installation Guide — Detailed methods and building from source
• MCP Integration — Connect to Claude, Cursor, etc.
• Commands Reference — Complete CLI reference
• Configuration — Templates and customization
• API Keys — Provider setup guide
• Architecture — How it works under the hood
• Contributing — Development setup

🔒 Privacy & Security

• 🏠 Local-first — FastEmbed runs entirely offline (macOS)
• 🔐 Secure — API keys stored locally, env vars supported
• 🚫 Respects .gitignore — Never indexes sensitive files
• 🛡️ MCP security — Local-only server, no external network for search
• 📤 Cloud-safe — Embeddings process only metadata, never source code

🤝 Community & Support

• ⭐ Star us on GitHub — It really helps!
• 🐛 Report Issues
• 💬 Discussions
• 📧 opensource@muvon.io
• 🌐 muvon.io

⚖️ License

Apache License 2.0 — See LICENSE for details.

---

Built with 🦀 Rust by Muvon in Hong Kong

⭐ Star • 🍴 Fork • 📣 Share