Overview
Codebase Research Agent answers deep questions about a codebase by reasoning over hybrid retrieval — combining dense vector search, lexical BM25, and AST-aware parsing — inside a ReAct agentic loop. It is exposed to Claude Code as an MCP server.
Architecture
- Retrieval: Hybrid search combining pgvector (semantic), BM25 (lexical), and AST-based structural parsing for precise code-symbol grounding.
- Agent loop: ReAct pattern with stateless, typed async tools, a maximum iteration cap, and a fallback answer path.
- MCP server: Streamable HTTP transport for Claude Code integration; tools return plain strings with progress reporting and a 30-second timeout.
- Quality: Eval suite with measurable retrieval metrics run on every change to the retrieval strategy.
Highlights
- Hybrid retrieval (vector + BM25 + AST) outperforms single-strategy search on code questions.
- Production-grade agent loop with bounded iterations and graceful fallback.
- Drop-in MCP server usable directly from Claude Code.
