Muvon/octocode: Semantic code searcher and codebase utility

© 2025 Muvon Un Limited (Hong Kong) | Website | Product Page

Octocode is a powerful code indexer and semantic search engine that builds intelligent knowledge graphs of your codebase. It combines advanced AI capabilities with local-first design to provide deep code understanding, relationship mapping, and intelligent assistance for developers.

• Natural language queries across your entire codebase
• Multi-mode search (code, documentation, text, or all)
• Intelligent ranking with similarity scoring
• Symbol expansion for comprehensive results

• Automatic relationship discovery between files and modules
• Import/export dependency tracking
• AI-powered file descriptions and architectural insights
• Path finding between code components

• Rust, Python, JavaScript, TypeScript, Go, PHP
• C++, Ruby, JSON, Bash, Markdown
• Tree-sitter based parsing for accurate symbol extraction

• Smart commit message generation
• Code review with best practices analysis
• Memory system for storing insights, decisions, and context
• Semantic memory search with vector similarity
• Memory relationships and automatic context linking
• Multiple LLM support via OpenRouter

• Built-in Model Context Protocol server
• Seamless integration with AI assistants (Claude Desktop, etc.)
• Real-time file watching and auto-reindexing
• Rich tool ecosystem for code analysis

• Optimized indexing: Batch metadata loading eliminates database query storms
• Smart batching: 16 files per batch with token-aware API optimization
• Frequent persistence: Data saved every 16 files (max 16 files at risk)
• Fast file traversal: Single-pass progressive counting and processing
• Local embedding models: FastEmbed and SentenceTransformer (macOS only)
• Cloud embedding providers: Voyage AI (default), Jina AI, Google
• Free tier available: Voyage AI provides 200M free tokens monthly
• Lance columnar database for fast vector search
• Incremental indexing and git-aware optimization

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

Or download manually from GitHub Releases.

cargo install --git https://github.com/Muvon/octocode

Prerequisites:

git clone https://github.com/Muvon/octocode.git
cd octocode

# macOS: Full build with local embeddings
cargo build --release

# Windows/Linux: Cloud embeddings only (due to ONNX Runtime issues)
cargo build --release --no-default-features

Note: Prebuilt binaries use cloud embeddings only. Local embeddings require building from source on macOS.

⚠️ Important: Octocode requires API keys to function. Local embedding models are only available on macOS builds.

export VOYAGE_API_KEY="your-voyage-api-key"

• Free tier: 200M tokens per month
• Get API key: voyageai.com
• Used for: Code and text embeddings (semantic search)

export OPENROUTER_API_KEY="your-openrouter-api-key"

• Get API key: openrouter.ai
• Used for: Commit messages, code review, GraphRAG descriptions
• Note: Basic search and indexing work without this

• Windows/Linux: Must use cloud embeddings (Voyage AI default)
• macOS: Can use local embeddings (build from source) or cloud embeddings

# Set Voyage AI API key for embeddings (free 200M tokens/month)
export VOYAGE_API_KEY="your-voyage-api-key"

# Optional: Set OpenRouter API key for LLM features (commit, review, GraphRAG)
export OPENROUTER_API_KEY="your-openrouter-api-key"

Get your free API keys:

# Index your current directory
octocode index

# Search your codebase
octocode search "HTTP request handling"

# View code signatures
octocode view "src/**/*.rs"

# Generate intelligent commit messages
git add .
octocode commit

# Review code for best practices
octocode review

# Start MCP server
octocode mcp

# Use with Claude Desktop or other MCP-compatible tools
# Provides: search_code, search_graphrag, memorize, remember, forget

# Store important insights and decisions
octocode memory memorize \
  --title "Authentication Bug Fix" \
  --content "Fixed JWT token validation in auth middleware" \
  --memory-type bug_fix \
  --tags security,jwt,auth

# Search your memory with semantic similarity
octocode memory remember "JWT authentication issues"

# Get memories by type, tags, or files
octocode memory by-type bug_fix
octocode memory by-tags security,auth
octocode memory for-files src/auth.rs

# Clear all memory data (useful for testing)
octocode memory clear-all --yes

# Enable GraphRAG with AI descriptions (requires OpenRouter API key)
octocode config --graphrag-enabled true
octocode index

# Search the knowledge graph
octocode graphrag search --query "authentication modules"

# Watch for changes
octocode watch

Octocode includes a powerful memory system for storing and retrieving project insights, decisions, and context using semantic search and relationship mapping.

• code – Code-related insights and patterns
• bug_fix – Bug reports and solutions
• feature – Feature implementations and decisions
• architecture – Architectural decisions and patterns
• performance – Performance optimizations and metrics
• security – Security considerations and fixes
• testing – Test strategies and results
• documentation – Documentation notes and updates

# Store a bug fix with context
octocode memory memorize \
  --title "JWT Token Validation Fix" \
  --content "Fixed race condition in token refresh logic by adding mutex lock" \
  --memory-type bug_fix \
  --importance 0.8 \
  --tags security,jwt,race-condition \
  --files src/auth/jwt.rs,src/middleware/auth.rs

# Search for authentication-related memories
octocode memory remember "JWT authentication problems" \
  --memory-types bug_fix,security \
  --min-relevance 0.7

# Get all security-related memories
octocode memory by-tags security --format json

# Clear all memory data (useful for testing/reset)
octocode memory clear-all --yes

Octocode stores configuration in ~/.local/share/octocode/config.toml.

# Set Voyage AI API key (required for embeddings)
export VOYAGE_API_KEY="your-voyage-api-key"

# Optional: Set OpenRouter API key for LLM features
export OPENROUTER_API_KEY="your-openrouter-api-key"

# View current configuration
octocode config --show

# Use local models (macOS only - requires building from source)
octocode config \
  --code-embedding-model "fastembed:jinaai/jina-embeddings-v2-base-code" \
  --text-embedding-model "fastembed:sentence-transformers/all-MiniLM-L6-v2-quantized"

# Use different cloud embedding provider
octocode config \
  --code-embedding-model "jina:jina-embeddings-v2-base-code" \
  --text-embedding-model "jina:jina-embeddings-v2-base-en"

# Enable GraphRAG with AI descriptions
octocode config --graphrag-enabled true

# Set custom OpenRouter model
octocode config --model "openai/gpt-4o-mini"

• Code embedding: voyage:voyage-code-2 (Voyage AI)
• Text embedding: voyage:voyage-2 (Voyage AI)
• LLM: openai/gpt-4o-mini (via OpenRouter)

• Windows/Linux: Cloud embeddings only (Voyage AI, Jina AI, Google)
• macOS: Local embeddings available (FastEmbed, SentenceTransformer) + cloud options

• 🏠 Local-first option: FastEmbed and SentenceTransformer run entirely offline (macOS only)
• 🔑 Secure storage: API keys stored locally, environment variables supported
• 📁 Respects .gitignore: Never indexes sensitive files or directories
• 🛡️ MCP security: Server runs locally with no external network access for search
• 🌐 Cloud embeddings: Voyage AI and other providers process only file metadata, not source code

This project is licensed under the Apache License 2.0 – see the LICENSE file for details.

Built with ❤️ by the Muvon team in Hong Kong

Keep your files stored safely and securely with the SanDisk 2TB Extreme Portable SSD. With over 69,505 ratings and an impressive 4.6 out of 5 stars, this product has been purchased over 8K+ times in the past month. At only $129.99, this Amazon’s Choice product is a must-have for secure file storage.

Help keep private content private with the included password protection featuring 256-bit AES hardware encryption. Order now for just $129.99 on Amazon!

Help Power Techcratic’s Future – Scan To Support

If Techcratic’s content and insights have helped you, consider giving back by supporting the platform with crypto. Every contribution makes a difference, whether it’s for high-quality content, server maintenance, or future updates. Techcratic is constantly evolving, and your support helps drive that progress.

As a solo operator who wears all the hats, creating content, managing the tech, and running the site, your support allows me to stay focused on delivering valuable resources. Your support keeps everything running smoothly and enables me to continue creating the content you love. I’m deeply grateful for your support, it truly means the world to me! Thank you!