octocode

Octocode uses a modular architecture designed for AI agents, separating code parsing, embedding generation, storage, and retrieval.

Key components include:

• Indexer Engine: Uses Tree-sitter for multi-language AST extraction and symbol detection.
• Embedding System: A multi-provider system (Jina, Voyage, Google, OpenAI, etc.) supporting both cloud and local (FastEmbed, HuggingFace) providers.
• Vector Database: Powered by Lance with RaBitQ quantization for high-speed, compressed similarity search.
• GraphRAG Builder: Extracts AI-powered relationships (imports, calls, dependencies) to build a knowledge graph.
• MCP Server: Implements the Model Context Protocol to expose tools like semantic search, GraphRAG, and LSP integration to AI agents.
• Search Engine: Provides semantic, hybrid, and reranked search capabilities.

Octocode uses several strategies to resolve symbols on a given line to ensure high reliability even with partial input:

1. Exact Match with Word Boundaries: Finds exact matches.
2. Substring Search: Finds symbols that are substrings within the line.
3. Case-Insensitive Match: Fallback for case mismatches.
4. Partial Identifier Matching: Finds symbols within larger identifiers.
5. Namespace Handling: Supports qualified names (e.g., std::vec::Vec).
6. Intelligent Fallback: Uses the first meaningful identifier if an exact match fails.

The embedding system supports multiple cloud and local providers. You can specify providers using the provider:model format.

Cloud Providers:

• Jina AI, Voyage AI, Google, OpenAI, OpenRouter, Together

Local Providers (Feature-gated):

• FastEmbed, HuggingFace (requires fastembed or huggingface features enabled during build).

Key Features:

• Dynamic Model Discovery: No hardcoded dimension mappings required.
• Provider Auto-detection: Automatically identifies the provider from the model string.
• Input Optimization: Supports different handling for queries vs. documents.

Structural search uses AST (Abstract Syntax Tree) patterns to understand code syntax rather than just matching text. This allows you to find patterns like function calls regardless of the specific variable names used.

Pattern Syntax:

• $VAR: Matches any single AST node (e.g., $FUNC.unwrap() matches foo.unwrap()).
• $$REST: Matches zero or more nodes.
• $$$ARGS: Matches function arguments (e.g., new $CLASS($$$ARGS)).
• Literal code: Matches exact structures like return 0.

Supported Languages: Rust, JavaScript, TypeScript, Python, Go, Java, C/C++, PHP, Ruby, Lua, Bash, CSS, JSON.

# Find all .unwrap() calls in Rust
octocode grep '$FUNC.unwrap()' --lang rust

# Find println calls in Java with 2 lines of context
octocode grep 'System.out.println($ARG)' --lang java -C 2

# Search specific paths
octocode grep 'return nil' --lang go --paths 'src/**/*.go'

The benchmark evaluates search performance using several key metrics:

• Hit@k: A binary metric per query. It checks if any correct result appears in the top-k results. A Hit@5 of 0.85 means 85% of queries had at least one relevant result in the top 5.
• MRR (Mean Reciprocal Rank): Measures how high the first correct result appears. It is the average of the reciprocal of the rank of the first correct result (e.g., rank 1 = 1.0, rank 2 = 0.5).
• NDCG@10 (Normalized Discounted Cumulative Gain): Accounts for both the relevance grade (e.g., primary vs. secondary) and the position in the ranking. It ensures the most relevant results are ranked highest.
• Recall@k: The fraction of ground truth entries found in the top-k results. It measures completeness (e.g., if 2 out of 3 ground truth blocks are found in top 10, Recall@10 = 0.67).

Octocode follows a two-phase pipeline to transform raw source code into a searchable, relational knowledge base.

1. Indexing Phase

This phase converts files into stored vectors and graph nodes: Source Files $\rightarrow$ Tree-sitter Parser $\rightarrow$ Symbol Extraction $\rightarrow$ Embedding Generation $\rightarrow$ Vector Storage
$\downarrow$
GraphRAG Analysis $\leftarrow$ AI Description Generation $\leftarrow$ Chunk Processing

2. Search Phase

This phase handles user queries: Query $\rightarrow$ Embedding Generation $\rightarrow$ Vector Similarity Search $\rightarrow$ Result Ranking $\rightarrow$ Response

Unlike standard RAG which treats code as flat text chunks, Octocode uses tree-sitter AST parsing to understand the actual structure of your code.

The Workflow:

1. AST Parsing: Extracts real symbols (functions, classes, imports) using tree-sitter.
2. Knowledge Graph (GraphRAG): Maps relationships between files (e.g., imports, calls, implements, extends, configures, and 9+ other types).
3. Hybrid Search: Combines semantic similarity with BM25 full-text search and reranking for high-precision retrieval.
4. MCP Server: Exposes these capabilities (semantic_search, view_signatures, graphrag) to AI tools.

This allows an AI to not just find similar text, but to navigate the dependency chain (e.g., knowing that auth_middleware.rs calls user_store.rs).

To serve multiple git repositories from a single MCP endpoint, use the --multi flag. Octocode will scan the immediate subdirectories of the provided --path for git repositories.

Key Features:

• Each repository gets its own store and background indexing threads.
• Indexing is performed lazily on first use.
• Important: Every tool call in this mode requires a project argument, which is the name of the subdirectory (the repository name) to select the target repository.

Commands:

• Stdio: octocode mcp --multi --path /path/to/parent/directory
• HTTP: octocode mcp --multi --bind "127.0.0.1:8080" --path /workspace

octocode mcp --multi --path /workspace

Octocode stores its configuration in ~/.local/share/octocode/config.toml. You can view your current active settings using the CLI. Note that environment variables always take priority over settings in the configuration file.

# View current configuration
octocode config --show

To enable semantic search and GraphRAG, you must first index your project. Navigate to your project directory and run the index command. This process scans supported files, extracts symbols, generates embeddings, and builds the knowledge graph in a local database.

Use the --verbose flag to monitor the indexing progress.

# Index current directory
octocode index

# Watch for progress
octocode index --verbose