semantic code search via natural language queries
Enables AI agents to find relevant code chunks across a codebase using natural language queries rather than regex or file browsing. The system converts user queries into embeddings using OpenAI's embedding API, then performs vector similarity search against a chromem-go vector database containing embeddings of all parsed code chunks. This approach dramatically reduces token consumption by returning only semantically relevant code segments instead of entire files.
Unique: Uses Tree-sitter AST-based code chunking (not simple line-based splitting) combined with chromem-go vector database for in-memory semantic search, enabling structurally-aware code discovery that respects language syntax boundaries rather than arbitrary text chunks
vs alternatives: More token-efficient than sending entire files to LLMs for search, and more semantically accurate than regex-based code search because it understands code structure through AST parsing
tree-sitter based code parsing and semantic chunking
Parses source code using Tree-sitter language parsers to build Abstract Syntax Trees (ASTs), then extracts semantic chunks at the granularity of functions, classes, methods, and interfaces. Each chunk receives a stable ID following the pattern file.ext::Type::method, enabling precise code retrieval and reference. The system supports Go, JavaScript, Python, TypeScript, and Markdown with language-specific extraction rules that respect syntactic boundaries.
Unique: Uses Tree-sitter AST parsing instead of regex or simple text splitting, enabling structurally-aware chunking that respects language syntax boundaries and extracts semantic units (functions, classes) with full context preservation
vs alternatives: More accurate than line-based or regex-based chunking because it understands actual code structure; more maintainable than custom parsers because Tree-sitter grammars are community-maintained and battle-tested
real-time file system monitoring with debounced indexing
Continuously monitors the workspace directory for file changes using file system watchers, detects modifications to source files, and triggers re-indexing of affected chunks with debouncing to avoid redundant parsing during rapid edits. The system respects .gitignore rules to exclude non-source files and maintains a queue of pending files awaiting indexing. This enables the semantic search index to stay synchronized with the codebase without manual refresh commands.
Unique: Implements debounced file watching with .gitignore respect and pending file tracking, avoiding the common pitfall of re-parsing the entire codebase on every keystroke while maintaining index freshness
vs alternatives: More efficient than full re-indexing on every change (like some code search tools) and more responsive than manual refresh commands because it automatically detects and processes only changed files
mcp protocol tool exposure for code discovery
Exposes semantic code search and navigation capabilities through the Model Context Protocol (MCP) as callable tools that AI agents can invoke. The system implements five primary MCP tools: semantic_search (natural language queries), get_chunk_code (retrieve by ID), find_similar_chunks (discover related code), index_workspace (manual re-indexing), and get_index_status (progress tracking). This integration allows Claude, other LLMs, and AI agents to treat code discovery as a native capability without custom API integration.
Unique: Implements MCP as the primary interface for tool exposure rather than REST or gRPC, enabling seamless integration with Claude and other MCP-compatible agents without custom API wrappers or authentication layers
vs alternatives: More standardized than custom REST APIs because MCP is a protocol designed specifically for AI tool integration; more agent-friendly than direct library imports because it works across language boundaries and client types
chunk-level code retrieval with stable identifiers
Retrieves specific code chunks by their stable IDs (format: file.ext::Type::method) without requiring file path knowledge or line number tracking. The system maintains a mapping from chunk IDs to their source locations and content, enabling precise code access that survives file edits and refactoring. This capability supports both direct ID-based retrieval and discovery of similar chunks through semantic comparison.
Unique: Uses Tree-sitter-derived stable IDs (file.ext::Type::method) that encode semantic structure rather than line numbers, enabling references that survive code edits and refactoring within the same semantic unit
vs alternatives: More robust than line-number-based references because code edits don't invalidate IDs; more precise than file-path-based retrieval because it targets specific functions/classes rather than entire files
vector database indexing and embedding generation
Builds and maintains a chromem-go in-memory vector database containing embeddings of all parsed code chunks. For each semantic chunk extracted by the parser, the system generates an embedding using OpenAI's embedding API, stores it in the vector database with the chunk ID and metadata, and enables fast similarity search. The database is rebuilt incrementally as files change, with new chunks added and deleted chunks removed from the index.
Unique: Uses chromem-go (lightweight in-memory vector database) instead of external vector stores like Pinecone or Weaviate, reducing operational complexity but trading persistence for simplicity
vs alternatives: Simpler to deploy than external vector databases because it's in-process; faster than cloud-based vector stores for small-to-medium codebases due to no network latency; more cost-effective than managed vector database services for development workflows
multi-language code analysis with language-specific extraction
Analyzes source code across five programming languages (Go, JavaScript, Python, TypeScript, Markdown) using language-specific Tree-sitter parsers and extraction rules. Each language parser understands language-specific constructs: Go extracts functions/methods/types/interfaces, JavaScript extracts functions/classes/variables, Python extracts functions/classes/decorators, TypeScript extracts functions/interfaces/enums/classes, and Markdown extracts sections/headings. This enables semantically accurate code chunking that respects language idioms and structure.
Unique: Implements language-specific extraction rules for each supported language rather than a generic chunking algorithm, enabling accurate semantic understanding of language idioms (e.g., Python decorators, TypeScript interfaces) that generic approaches would miss
vs alternatives: More accurate than language-agnostic chunking because it understands language-specific syntax and semantics; more maintainable than custom parsers because Tree-sitter grammars are community-maintained
indexing progress tracking and status reporting
Provides visibility into the indexing state of the workspace through a get_index_status MCP tool that reports current progress, lists files pending indexing, and indicates whether the index is fully synchronized with the file system. The system tracks which files have been parsed, which are queued for processing, and provides status updates without blocking ongoing searches. This enables agents and users to understand index freshness and plan queries accordingly.
Unique: Exposes indexing state as a queryable MCP tool rather than just logging to stdout, enabling agents and clients to make decisions based on index freshness and plan queries accordingly
vs alternatives: More actionable than silent background indexing because clients can verify index state; more efficient than blocking all searches until indexing completes because searches can proceed on partially-indexed codebases
+1 more capabilities