by Muvon
Semantic code searcher and codebase utility
# Add to your Claude Code skills
git clone https://github.com/Muvon/octocodeGuides for using mcp servers skills like octocode.
Last scanned: 5/24/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-05-24T07:23:36.847Z",
"semgrepRan": false,
"npmAuditRan": true,
"pipAuditRan": true
}No comments yet. Be the first to share your thoughts!
Top skills in this category by stars
Give your AI assistant a brain for your codebase. Octocode transforms your project into a navigable knowledge graph that Claude, Cursor, and other AI agents can search, understand, and navigate.
🚀 Quick Start • 🤖 MCP Integration • 📖 Documentation • 🌐 Website
The Problem: AI assistants are blind to your codebase. They can't search your files, understand dependencies, or remember context across sessions.
The Solution: Octocode's MCP server gives AI agents:
Works with: Claude Desktop • Cursor • Windsurf • Any MCP-compatible AI
// Add to your AI assistant config
{
"mcpServers": {
"octocode": {
"command": "octocode",
"args": ["mcp", "--path", "/your/project"]
}
}
}
Now your AI assistant can:
You: "Where is authentication handled?"
AI: *searches your codebase* "Authentication is in src/middleware/auth.rs,
which imports jwt.rs for token validation and calls user_store.rs for lookup."
You: "What files depend on the payment module?"
AI: *queries knowledge graph* "src/api/handlers/payment.rs imports payment/mod.rs,
which is also used by src/workers/refund.rs and src/cron/billing.rs"
You: "Remember this bug fix for future reference"
AI: *stores in memory* "Got it. I'll remember this authentication bypass fix
and apply similar patterns when reviewing security code."
Standard RAG treats your code as flat text chunks. It finds similar-sounding snippets but has no idea that auth_middleware.rs imports jwt.rs, calls user_store.rs, and is wired into router.rs. Octocode understands structure.
# Semantic search finds the right code
octocode search "authentication middleware"
→ src/middleware/auth.rs | Similarity 0.923
# GraphRAG reveals the full dependency chain
octocode graphrag get-relationships --node_id src/middleware/auth.rs
Outgoing:
imports → jwt (src/auth/jwt.rs): token validation logic
calls → user_store (src/db/user_store.rs): user lookup by token
Incoming:
imports ← router (src/router.rs): wires auth into the request pipeline
Octocode uses tree-sitter AST parsing to extract real symbols (functions, imports, dependencies), builds a GraphRAG knowledge graph of relationships between files, and exposes everything via MCP — so AI tools can navigate your project architecture, not just search it.
Source Code → Tree-sitter AST → Symbols & Relationships → Knowledge Graph
↓
Embeddings + Hybrid Search + Reranking → MCP Server
imports, calls, implements, extends, configures, and 9 more types — each with importance weightingsemantic_search, view_signatures, and graphrag tools to any MCP-compatible client| | Standard RAG | Doc Lookup Tools | Octocode |
|---|---|---|---|
| Indexes | Text chunks | External library docs | Your codebase structure (AST) |
| Understands | Similar text | API specs & usage | Functions, imports, dependencies |
| Cross-file | No | No | Yes — navigates the dependency graph |
| Relationships | No | No | imports, calls, implements, extends... |
| AI integration | Varies | MCP | Native MCP server + LSP |
Doc tools give AI the manual for libraries you use. Octocode gives AI the blueprint of how you put them together.
Built with Rust for performance. Local-first for privacy. Open source (Apache 2.0) for transparency.
# Universal installer (Linux, macOS, Windows)
curl -fsSL https://raw.githubusercontent.com/Muvon/octocode/master/install.sh | sh
# macOS with Homebrew
brew install muvon/tap/octocode
# Cargo (build from source)
cargo install --git https://github.com/Muvon/octocode
# Download binary from releases
# https://github.com/Muvon/octocode/releases
See Installation Guide for platform-specific instructions.
# Required: Embedding provider (Voyage AI has 200M free tokens/month)
export VOYAGE_API_KEY="your-voyage-api-key"
# Optional: LLM for commit messages, code review
export OPENROUTER_API_KEY="your-openrouter-api-key"
Get your Voyage API key: voyageai.com (free tier available)
Octocode supports multiple embedding providers:
# OpenAI
export OPENAI_API_KEY="your-key"
octocode config --code-embedding-model "openai:text-embedding-3-small"
# Jina AI
export JINA_API_KEY="your-key"
octocode config --code-embedding-model "jina:jina-embeddings-v3"
# Google
export GOOGLE_API_KEY="your-key"
octocode config --code-embedding-model "google:text-embedding-005"
See API Keys guide for all supported providers.
cd /your/project
octocode index
# → Indexed 12,847 blocks across 342 files
# Natural language search
octocode search "authentication middleware"
# Multi-query for broader results
octocode search "auth" "middleware" "session"
# Filter by language
octocode search "database connection pool" --lang rust
# Search commit history
octocode search "authentication refactor" --mode commits
Add to your MCP client config (Claude Desktop, Cursor, Windsurf):
{
"mcpServers": {
"octocode": {
"command": "octocode",
"args": ["mcp", "--path", "/your/project"]
}
}
}
Done! Your AI assistant now understands your codebase structure.
Octocode includes a built-in MCP server that exposes your codebase as tools to AI assistants. This is the primary way to use Octocode — give your AI assistant direct access to search and navigate your code.
| Tool | What It Does |
|------|--------------|
| semantic_search | Find code by meaning — "authentication flow", "error handling", "database queries" |
| view_signatures | View file structure — function signatures, class definitions, imports |
| graphrag | Query relationships — "what calls this function?", "what does this module import?" |
| structural_search | AST pattern matching — find .unwrap() calls, new instantiations, specific patterns |
Once connected, your AI assistant can answer questions about your codebase:
You: "Where is user authentication implemented?"
AI: *uses semantic_search* "Found in src/auth/login.rs. The authenticate() function
validates credentials against the database, generates a JWT token, and stores
the session in Redis."
You: "What files depend on the payment module?"
AI: *uses graphrag* "src/api/handlers/payment.rs imports payment/mod.rs, which is also
used by src/workers/refund.rs and src/cron/billing.rs. The payment module exports
process_payment() and validate_transaction() functions."
You: "Show me all error handling in the API layer"
AI: *uses structural_search* "Found 23 error handling patterns in src/api/:
- 15 use Result<T, ApiError> with explicit error types
- 8 use .unwrap() (potential panics in handlers/user.rs:42, handlers/auth.rs:87)
- 3 use .expect() with custom messages"
Octomind (Recommended) — Zero setup, Octocode pre-configured:
curl -fsSL https://raw.githubusercontent.com/muvon/octomind/master/install.sh | bash
octomind run developer:rust
Claude Code (CLI) — Command-line setup:
claude mcp add octocode -- octocode mcp --path /path/to/your/project
Claude Desktop / Cursor / Windsurf — Add to config:
{
"mcpServers": {
"octocode": {
"command": "octocode",
"args": ["mcp", "--path", "/path/to/your/project"]
}
}
}
Config locations:
~/Library/Application Support/Claude/claude_desktop_config.json (macOS)~/.cursor/mcp.json or Settings → MCP Servers📖 Complete MCP Client Setup Guide — Detailed instructions for 15+ clients including VS Code (Cline/Continue), Zed, Replit, and more.
New developer onboarding:
You: "How does the authentication sys