Code Expert - Deep Research for Code & Files

From Simple Search to Deep Research

Traditional search: “Find validateEmail” Deep Research: “Understand all validation patterns, find existing email validators AND their written context, map their usage, identify the preferred approach with reasoning”

The Code Expert Agent performs Deep Research across code and files - an iterative, comprehensive analysis that:

Starts with your intent
Discovers semantically related code AND files
Maps architectural relationships across implementation and design
Identifies existing solutions with their written context
Synthesizes actionable insights from the complete engineering story

Why Deep Research Changes Everything

Without understanding your complete context, AI creates:

Generic code that doesn’t match your team’s patterns
Duplicate implementations of existing solutions
Changes that break architectural consistency
Features that conflict with written specifications
Security vulnerabilities from missed context

Code Expert performs deep research first - understanding your coding style, existing solutions, architectural patterns, design specifications, and security requirements before suggesting any changes.

What Code Deep Research Provides

Stop Reinventing the Wheel

Your team has already solved most problems. The challenge is finding those solutions. Code Deep Research discovers existing implementations, patterns, and conventions - preventing duplicate code and maintaining consistency.

Understand Before You Code

Map the architecture before making changes
Trace dependencies to avoid breaking changes
Learn conventions from existing patterns
Find examples of similar implementations

Scale AI Without Losing Context

Focused retrieval: Only relevant code, not entire files
Semantic understanding: “authentication” finds login(), validateUser(), checkCredentials()
Multi-hop discovery: Follow code relationships to complete understanding
Enterprise scale: Millions of lines, millisecond responses

The Code Expert leverages ChunkHound’s powerful search tools—including multi-hop semantic search and regex pattern matching—to provide this deep understanding rather than just returning search results.

Code Deep Research in Action

Example: “Add authentication to new API endpoint”

Without Deep Research: ❌ AI creates new auth middleware ❌ Duplicates existing JWT validation ❌ Inconsistent with team patterns ❌ Misses role-based permissions

With Code Expert Deep Research: ✅ Discovers existing AuthMiddleware in middleware/ ✅ Maps usage patterns across endpoints ✅ Identifies JWT + role validation approach ✅ Finds configuration in config/auth.yaml ✅ Locates permission decorator examples ✅ Result: Consistent, secure implementation

Example: “Debug payment processing failure”

Deep Research Process:

Initial: Finds PaymentProcessor class
Hop 1: Discovers StripeHandler, PayPalHandler
Hop 2: Maps to PaymentQueue, RetryPolicy
Hop 3: Traces to WebhookValidator, AuditLogger
Hop 4: Connects to NotificationService
Result: Complete payment flow architecture mapped

When to Use Code Deep Research

Before Adding Features

Find existing patterns and reusable components first

Complex Bug Investigation

Map all connected components and data flows

Large Refactoring

Understand all dependencies and usage patterns

New Codebase Onboarding

Get architectural overview and coding conventions

Code Review Preparation

Understand context around changes being made

Enterprise Migration

Map legacy systems before modernization

Prerequisites

Before using the Code Expert Agent, you need ChunkHound set up and running:

First-Time Setup

New to ChunkHound? Start with the Quickstart to install, configure, and index your first codebase.

Advanced Configuration

Need semantic search? The Code Expert Agent requires semantic search capabilities. See the Configuration guide to set up embedding providers like OpenAI or VoyageAI.

MCP Integration

IDE Setup Required The agent works through MCP (Model Context Protocol). Your AI assistant must be configured to connect to ChunkHound as described in the Quickstart.

How to Enable Code Deep Research

1. Create the Code Expert Agent

Create a markdown file .claude/agents/code-expert.md with the following content:

---
name: Code Expert

description: Use this **READ ONLY** agent (**CAN'T WRITE TO FILES**) to perform Code Deep Research - iterative, comprehensive analysis that discovers existing solutions, maps architectural relationships, and identifies patterns before coding. This agent prevents duplicate implementations by finding what already exists and understanding how it fits in your codebase. Examples: <example>Context: User needs to add a new feature. user: "I need to add authentication to this new endpoint" assistant: "Let me perform code deep research to understand our existing authentication architecture first" <commentary>Before creating new auth code, we need to discover existing auth middleware, understand current patterns, and find reusable components.</commentary></example> <example>Context: User is debugging a complex issue. user: "Payment processing is failing intermittently" assistant: "I'll use code deep research to map the complete payment flow and identify all connected components" <commentary>Deep research will trace from payment entry through processing, validation, storage, and notification to understand the full architecture.</commentary></example> <example>Context: User wants to refactor code. user: "This validation logic is scattered everywhere" assistant: "Let me research all validation patterns in the codebase before we refactor" <commentary>Code deep research will find all validators, identify patterns, map dependencies, and suggest consolidation opportunities.</commentary></example>

tools: Glob, Grep, Bash, Read, TodoWrite, mcp__ChunkHound__get_stats, mcp__ChunkHound__health_check, mcp__ChunkHound__search_semantic, mcp__ChunkHound__search_regex

---

You are an expert code researcher with deep experience across all software domains. Your mission is comprehensive code analysis - discovering existing implementations, understanding system design, identifying patterns, and mapping relationships before any coding begins.

**Research Methodology:**

1. **Discovery Phase:**
   - Start with README and documentation for project context
   - List relevant directories
   - Use semantic search for key concepts relevant to the task
   - Find configuration files to understand system setup
   - Locate entry points and main execution paths

2. **Code Mapping:**
   - Map directory structure and module organization
   - Identify component responsibilities and boundaries
   - Trace data flow and execution paths
   - Document interfaces and contracts
   - Understand dependencies and integrations

3. **Pattern Analysis:**
   - Identify design patterns and coding conventions
   - Recognize architectural decisions and trade-offs
   - Find reusable components and utilities
   - Spot inconsistencies or technical debt
   - Understand error handling and edge cases

4. **Deep Investigation:**
   For each relevant component:
   - Purpose and responsibilities
   - Key functions/classes with their roles
   - Dependencies (incoming/outgoing)
   - Data structures and algorithms
   - Performance and concurrency considerations

5. **Search Strategy:**
   - Semantic search for concepts and relationships
   - Regex search for specific patterns and syntax
   - Start broad, then narrow based on findings
   - Cross-reference multiple search results

**Output Format:**
```
## Overview
[System/feature purpose and design approach]

## Structure & Organization
[Directory layout and module organization]
[Key design decisions observed]

## Component Analysis
[Component Name]

- **Purpose**: [What it does and why]
- **Location**: [Files and directories]
- **Key Elements**: [Classes/functions with line numbers]
- **Dependencies**: [What it uses/what uses it]
- **Patterns**: [Design patterns and conventions]
- **Critical** Sections: [Important logic with file:line refs]

## Data & Control Flow
[How data moves through relevant components]
[Execution paths and state management]

## Patterns & Conventions
[Consistent patterns across codebase]
[Coding standards observed]

## Integration Points
[APIs, external systems, configurations]

## Key Findings
[Existing solutions relevant to the task]
[Reusable components identified]
[Potential issues or improvements]

## Relevant Code Chunks
[Description]

- **File**: [Path]
- **Lines**: [Start-End]
- **Relevance**: [Why this matters for the current task]
```

**Quality Principles:**
- Always provide specific file paths and line numbers
- Explain the 'why' behind code organization when evident
- Connect findings to the immediate task at hand
- Focus on actionable insights for development
- State assumptions explicitly when patterns are unclear

**Search Optimization:**
- Start with semantic searches, refine with regex
- Check test files to understand component behavior
- Look for documentation in each major directory
- Search TODO/FIXME for known issues
- Keep queries focused and iterative

Remember: Your analysis should provide developers with a clear understanding of existing code to prevent duplication and ensure new code integrates properly. Every finding should be backed by specific code references.

2. Perform Code Deep Research

Once ChunkHound is indexed and your MCP server is running, ask the Code Expert to research before you implement:

Instead of:

"Add rate limiting to the API"

Do this first:

"Use the code expert to research our current rate limiting approach,
find existing middleware, and understand the configuration patterns
before I implement rate limiting for the new endpoint"

This triggers deep research that:

Maps existing rate limiting architecture
Identifies reusable components
Documents configuration patterns
Provides implementation guidance

3. Code Deep Research Example

When you ask the Code Expert to research rate limiting, it performs iterative discovery:

Step 1: Initial Discovery

Searches for “rate limit”, “throttle”, “quota”
Finds RateLimitMiddleware in src/middleware/
Discovers configuration files

Step 2: Architectural Mapping

Maps middleware usage across endpoints
Identifies Redis-based storage approach
Traces to configuration and monitoring

Step 3: Pattern Analysis

Documents team conventions
Finds similar implementations
Identifies reusable components

Step 4: Implementation Guidance

Provides specific file locations
Shows configuration examples
Suggests consistent approach

4. The Result: Deep Understanding

Instead of creating duplicate code, you get actionable insights like:

## Rate Limiting Architecture Analysis

### Existing Implementation
- **Core**: `RateLimitMiddleware` (src/middleware/auth.ts:45-120)
- **Storage**: Redis-based with `ioredis` client
- **Config**: Environment-based limits in `config/limits.yaml`

### Usage Patterns
- Applied to 12 API endpoints
- Per-user and per-IP limiting
- Sliding window algorithm
- Custom headers for limit status

### Recommended Approach
Reuse existing middleware with endpoint-specific configuration:
```typescript
app.use('/api/new-endpoint', rateLimiter({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100 // limit each IP to 100 requests per windowMs
}));

<details>
<summary>Click to expand full code expert response</summary>
**Code Expert Response:**
`````markdown
Now I have comprehensive understanding of the multi-hop semantic search algorithm in ChunkHound. Let me provide a detailed explanation of how it works.

## ChunkHound Multi-Hop Semantic Search Algorithm Analysis

Based on my analysis of the codebase, I can provide a comprehensive explanation of how the multi-hop semantic search algorithm works in ChunkHound.

## System Overview

ChunkHound implements a sophisticated Dynamic Multi-Hop Semantic Search algorithm that combines embedding-based similarity search with reranking to discover semantically related code that wouldn't be found in standard single-hop searches. The algorithm automatically activates when the embedding provider supports reranking functionality.

## Core Architecture

### Key Components

1. **SearchService** (`chunkhound/services/search_service.py`)
   - Main orchestrator that decides between standard and multi-hop search
   - Lines 77-91: Strategy selection based on provider capabilities

2. **Multi-hop Algorithm** (`_search_semantic_multi_hop` method)
   - Lines 151-403: Complete multi-hop implementation
   - Dynamic expansion with relevance-based termination

3. **Database Provider** (DuckDB/LanceDB implementations)
   - `find_similar_chunks` method: Core similarity expansion functionality
   - Vector similarity using cosine distance

4. **Reranking Provider** (OpenAI/VoyageAI/Ollama)
   - `supports_reranking()` method: Capability detection
   - `rerank()` method: Relevance scoring against original query

## Algorithm Flow

### Phase 1: Strategy Selection

```python
# Lines 78-81 in search_service.py
if (hasattr(embedding_provider, "supports_reranking")
    and embedding_provider.supports_reranking()):
    return await self._search_semantic_multi_hop(...)

Multi-hop triggers when:

Embedding provider has rerank_model configured
Provider implements supports_reranking() returning True

Phase 2: Initial Search & Reranking

# Lines 167-176: Initial search with 3x expansion
initial_limit = min(page_size * 3, 100)  # Cap at 100 for performance
initial_results = await self._search_semantic_standard(
    query=query, page_size=initial_limit, threshold=0.0, ...
)

Key behaviors:

Searches for 3x requested results (capped at 100)
Uses threshold=0.0 to cast a wide net initially
Falls back to standard search if < 5 results found

Phase 3: Dynamic Expansion Loop

# Lines 240-372: Iterative expansion with termination conditions
while True:
    # Get top 5 candidates for expansion
    top_candidates = [r for r in all_results if r.get("score", 0.0) > 0.0][:5]

    # Find similar chunks for each candidate
    for candidate in top_candidates:
        neighbors = self._db.find_similar_chunks(
            chunk_id=candidate["chunk_id"],
            provider=provider, model=model,
            limit=20, threshold=None
        )

Expansion mechanics:

Each iteration expands from top 5 highest-scoring results
Uses find_similar_chunks to find 20 neighbors per candidate
Deduplicates using seen_chunk_ids set
Reranks ALL results (old + new) after each expansion

Phase 4: Termination Conditions

The algorithm stops when any condition is met:

Time limit: 5 seconds elapsed (Line 242)
Result limit: 500 total results (Line 247)
Insufficient candidates: < 5 high-scoring candidates (Line 253)
No new discoveries: No new chunks found in expansion (Line 287)
Score degradation: Tracked chunk scores drop ≥ 0.15 (Line 355)
Quality threshold: Minimum top-5 score < 0.5 (Line 362)

Phase 5: Final Filtering & Pagination

# Lines 377-403: Apply thresholds and pagination
if threshold is not None:
    all_results = [r for r in all_results if r.get("score", 0.0) >= threshold]

paginated_results = all_results[offset : offset + page_size]

Key Data Structures

RerankResult

# /Users/ofri/Documents/GitHub/chunkhound/chunkhound/interfaces/embedding_provider.py:9-12
@dataclass
class RerankResult:
    index: int    # Position in documents array
    score: float  # Relevance score (0.0-1.0)

Search Results

Each result contains:

chunk_id: Database identifier
content: Code content
score: Reranking score (primary sort key)
similarity: Original embedding similarity
File metadata (path, language, lines)

Configuration Options

Multi-hop Enablement

# /Users/ofri/Documents/GitHub/chunkhound/chunkhound/core/config/embedding_config.py:64-66
rerank_model: str | None = Field(
    default=None,
    description="Reranking model name (enables multi-hop search if specified)"
)

Rerank Endpoint

rerank_url: str = Field(
    default="/rerank",
    description="Rerank endpoint URL. Absolute URLs (http/https) used as-is for separate services."
)

Performance Tuning Constants

Initial expansion: 3x page_size (capped at 100)
Neighbors per candidate: 20
Top candidates per round: 5
Time limit: 5 seconds
Result limit: 500 chunks
Score degradation threshold: 0.15
Quality threshold: 0.5

What Makes It “Multi-Hop”

Traditional Single-Hop

Query → Embedding
Vector similarity search
Return top-K results

ChunkHound Multi-Hop

Query → Initial embedding search → Rerank
Hop 1: Find similar chunks to top results
Hop 2: Find similar chunks to newly discovered results
Hop N: Continue until termination conditions
Final reranking against original query

Semantic Bridging Effect

Query: “authentication error handling”

Hop 1: Direct matches

auth_error_handler()
validate_credentials()

Hop 2: Semantic bridges

error_logger() (shares error handling patterns)
token_validator() (shares auth patterns)

Hop 3: Distant discoveries

database_retry() (shares error patterns via logger)
session_cleanup() (shares auth lifecycle via tokens)

Optimization Features

Performance Safeguards

Batched reranking: All results reranked together (not incrementally)
Deduplication: seen_chunk_ids prevents duplicate processing
Early termination: Multiple conditions prevent runaway expansion
Index optimization: Uses vector indexes for similarity search

Quality Controls

Score tracking: Monitors score degradation of original top results
Relevance filtering: Maintains minimum quality thresholds
Content-aware: Reranking ensures relevance to original query

Architecture Insights

Strengths

Automatic activation: No user configuration needed
Semantic bridging: Discovers indirectly related code
Quality preservation: Reranking maintains query relevance
Performance bounds: Multiple termination safeguards
Extensible: Works with any reranking-capable provider

Design Trade-offs

Latency: Multi-hop takes 2-5 seconds vs. milliseconds for single-hop
API costs: More embedding/reranking calls
Complexity: Additional failure modes and edge cases
Memory: Maintains larger result sets during processing

Relevant Code Locations

Core Implementation

Main algorithm: chunkhound/services/search_service.py:151-403
Strategy selection: Lines 77-102
Expansion loop: Lines 240-372
Termination logic: Lines 242-367

Supporting Components

Database similarity: chunkhound/providers/database/duckdb_provider.py:1942-2070
Reranking interface: chunkhound/interfaces/embedding_provider.py:9-12
OpenAI reranking: chunkhound/providers/embeddings/openai_provider.py:693-815

Configuration

Embedding config: chunkhound/core/config/embedding_config.py:64-66
Provider factory: chunkhound/embeddings.py:148-167

Testing

Multi-hop tests: chunkhound/tests/test_multi_hop_semantic_search.py:1-100
Test documentation: Lines 1-13 explain semantic bridging test strategy

The algorithm represents a sophisticated approach to code search that goes beyond simple similarity matching to discover semantically related code through iterative expansion and relevance scoring.

</details>

**Final Orchestrator Answer**

*Note: The detailed file paths, line numbers, and code references below come from ChunkHound's indexed codebase. The Code Expert Agent uses ChunkHound's [semantic search](/under-the-hood/#semantic-search-architecture) and regex search tools to discover and analyze these code locations.*

`````markdown
ChunkHound implements a Dynamic Multi-Hop Semantic Search algorithm that discovers semantically related code through iterative expansion and reranking. Here's how it works:

## Core Concept: Semantic Bridging

Unlike traditional single-hop search that only finds direct matches, multi-hop search discovers indirectly related code by following semantic connections:

Query: "authentication error handling"
├── Hop 0: `auth_error_handler()`, `validate_credentials()`
├── Hop 1: `error_logger()`, `token_validator()`
└── Hop 2: `database_retry()`, `session_cleanup()`

## Algorithm Flow

1. **Automatic Activation** (search_service.py:77-91)
   - Triggers when embedding provider has `rerank_model` configured
   - Falls back to standard search if reranking unavailable

2. **Initial Expansion** (search_service.py:167-176)
   - Searches for 3x requested results (max 100)
   - Reranks all results against original query

3. **Iterative Discovery Loop** (search_service.py:240-372)
   - Takes top 5 highest-scoring results
   - Finds 20 similar chunks for each using vector similarity
   - Reranks ALL results (old + new) against original query
   - Repeats until termination conditions met

4. **Smart Termination** - Stops when:
   - 5 seconds elapsed
   - 500 total results found
   - Score degradation ≥ 0.15 detected
   - No new chunks discovered
   - Quality drops below threshold

## Key Implementation Details

**Primary Components:**
- `SearchService._search_semantic_multi_hop()` - Main orchestrator
- `DatabaseProvider.find_similar_chunks()` - Vector similarity expansion
- `EmbeddingProvider.rerank()` - Relevance scoring

**Performance Optimizations:**
- Batched reranking (not incremental)
- Deduplication via `seen_chunk_ids` set
- Multiple early termination conditions
- Configurable expansion limits

## What Makes It "Multi-Hop"

The algorithm performs multiple "hops" through semantic space:
- Each hop expands from previously discovered results
- Results from one hop become seeds for the next
- Reranking ensures all results stay relevant to original query
- Discovers code related through intermediate semantic bridges

## Configuration

Enable by setting `rerank_model` in embedding config:

```yaml
embedding:
  provider: openai
  model: text-embedding-3-small
  rerank_model: rerank-v3.5  # Enables multi-hop
```

The algorithm balances exploration (finding new semantic connections) with exploitation (maintaining query relevance) through continuous reranking against the original query.