CodeSeeker

Four-layer hybrid search and knowledge graph for AI coding assistants.
BM25 + vector embeddings + RAPTOR directory summaries + graph expansion — fused into a single MCP tool that gives Claude, Copilot, and Cursor a real understanding of your codebase.

Works withClaude Code,GitHub Copilot(VS Code 1.99+),Cursor,Windsurf, andClaude Desktop.
Zero configuration — indexes on first use, stays in sync automatically.

AI assistants are powerful editors, but they navigate code like a tourist:

- Grep finds text— not meaning."find authentication logic"returns every file containing the word "auth"
- File reads are isolated— Claude sees a file but not its dependencies, callers, or the patterns your team established
- No memory of your project— every session starts from scratch

CodeSeeker fixes this. It indexes your codebase once and gives AI assistants a queryable knowledge graph they can use on every turn.

Query: "find JWT refresh token logic" │ ▼ Stage 1 — Hybrid retrieval ┌─────────────────────────────────────────────────────┐ │ BM25 (exact symbols, camelCase tokenized) │ │ + │ │ Vector search (384-dim Xenova embeddings) │ │ ↓ │ │ Reciprocal Rank Fusion: score = Σ 1/(60 + rank_i) │ │ Top-30 results, including RAPTOR directory nodes │ └─────────────────────────────────────────────────────┘ │ ▼ Stage 2 — RAPTOR cascade (conditional) ┌─────────────────────────────────────────────────────┐ │ IF best directory-summary score ≥ 0.5: │ │ → narrow results to that directory automatically │ │ ELSE: all 30 results pass through unchanged │ │ Effect: "what does auth/ do?" scopes to auth/ │ │ "jwt.ts decode function" bypasses this │ └─────────────────────────────────────────────────────┘ │ ▼ Stage 3 — Scoring and deduplication ┌─────────────────────────────────────────────────────┐ │ Dedup: keep highest-score chunk per file │ │ Source files: +0.10 (definition sites matter) │ │ Test files: −0.15 (prevent test dominance) │ │ Symbol boost: +0.20 (query token in filename) │ │ Multi-chunk: up to +0.30 (file has many hits) │ └─────────────────────────────────────────────────────┘ │ ▼ Stage 4 — Graph expansion ┌─────────────────────────────────────────────────────┐ │ Top-10 results → follow IMPORTS/CALLS/EXTENDS edges │ │ Structural neighbors scored at source × 0.7 │ │ Avg graph connectivity: 20.8 edges/node │ └─────────────────────────────────────────────────────┘ │ ▼ auth/jwt.ts (0.94), auth/refresh.ts (0.89), ...

The knowledge graph is built from AST-parsed imports at index time. It's what powersanalyze dependencies, dead-code detection, and graph expansion in every search.

- "Find code that handles errors like this"→ semantic pattern search
- "What validation approach does this project use?"→ auto-detected coding standards
- "Show me everything related to authentication"→ graph traversal across indirect dependencies

- Direct import/export chains
- Class inheritance hierarchies
- Which files actually depend on which

The standard way to configure any MCP server — no global install required:

{ "mcpServers": { "codeseeker": { "command": "npx", "args": ["-y", "codeseeker", "serve", "--mcp"] } } }

Add this to your MCP config file (see belowfor per-client locations) and restart your editor.

npm install -g codeseeker codeseeker install --vscode # or --cursor, --windsurf

/plugin install codeseeker@github:jghiringhelli/codeseeker#plugin

{ "name": "My Project", "image": "mcr.microsoft.com/devcontainers/javascript-node:18", "postCreateCommand": "npm install -g codeseeker && codeseeker install --vscode" }

{ "mcpServers": { "codeseeker": { "command": "npx", "args": ["-y", "codeseeker", "serve", "--mcp"] } } }

npm install -g codeseeker cd your-project codeseeker init codeseeker -c "how does authentication work in this project?"

Once configured, Claude has access to these MCP tools (used automatically):

You don't invoke these manually—Claude uses them automatically when searching code or analyzing relationships.

You don't need to manually index.When Claude uses any CodeSeeker tool, the tool automatically checks if the project is indexed. If not, it indexes on first use.

User: "Find the authentication logic" │ ▼ ┌─────────────────────────────────────┐ │ Claude calls search({query: ...}) │ │ │ │ │ ▼ │ │ Project indexed? ──No──► Index now │ │ │ (auto) │ │ Yes │ │ │ │◀───────────────────┘ │ │ ▼ │ │ Return search results │ └─────────────────────────────────────┘

First search on a new project takes 30 seconds to several minutes (depending on size). Subsequent searches are instant.

18 hand-labelled queries across two real-world codebases:

Each query has one or moremustFindtargets (exact file basenames) and optionalmustNotFindtargets (scope leak check). Queries were run on a real index built from source — real Xenova embeddings, real graph, real RAPTOR L2 nodes — to reflect production conditions.

Metrics:MRR(Mean Reciprocal Rank),P@1(Precision at 1),R@5(Recall at 5),F1@3.

BM25 + embedding fusion (RRF)
The workhorse. Handles ~94% of ranking quality on its own. BM25 catches exact symbol names and camelCase tokens; vector embeddings catch semantic similarity when names differ. Fused with Reciprocal Rank Fusion to combine both signals without manual weight tuning.

RAPTOR (hierarchical directory summaries)
Generates per-directory embedding nodes by mean-pooling all file embeddings in a folder. Acts as a post-filter: when a directory summary scores ≥ 0.5 against the query, results are narrowed to that directory's files. Measured contribution:+0.3% MRRon symbol queries. Fires conservatively — only when the directory is an obvious match. Its real value is onabstract queries("what does the payments module do?") which don't appear in this benchmark; for those queries it prevents broad scattering across the entire codebase.

Knowledge graph (import/dependency edges)
Average connectivity: 20.8 file→file edges per node across both TS and C# codebases. Measured ranking impact:±0% MRRfor 1-hop expansion. The graph doesn't move MRR because the semantic layer already finds the right files — the graph's neighbors are usually already in the top-15. Its value is structural: theanalyze dependenciesaction and explicitgraphsearch type give Claude traversable import chains, inheritance hierarchies, and dependency paths that embeddings alone cannot provide.

Type boost / penalty scoring
Source files get +0.10 score boost; test files get −0.15 penalty; lock files and docs get −0.05 penalty. Without this,integration.test.tswould rank abovedag-engine.tsfor exact symbol queries because test files import and exercise every symbol in the source. The penalty corrects this without eliminating test files from results.

Monorepo directory exclusion fix
The single highest-impact change in v1.12.0: removingpackages/from the default exclusion list. For pnpm/yarn/lerna monorepos where all source lives underpackages/, this exclusion was silently dropping all source files. Effect:10% → 72% MRRon the Conclave monorepo benchmark.

npm run build node scripts/real-bench.js

RequiresC:\workspace\claude\conclaveandC:\workspace\ImperialCommander2to be present locally (or update paths inscripts/real-bench.js).

CodeSeeker analyzes your codebase and extracts patterns:

{ "validation": { "email": { "preferred": "z.string().email()", "usage_count": 12, "files": ["src/auth.ts", "src/user.ts"] } }, "react-patterns": { "state": { "preferred": "useState<T>()", "usage_count": 45 } } }

- validation: Zod, Yup, Joi, validator.js, custom regex
- error-handling: API error responses, try-catch patterns, custom Error classes
- logging: Console, Winston, Bunyan, structured logging
- testing: Jest/Vitest setup, assertion patterns
- react-patterns: Hooks (useState, useEffect, useMemo, useCallback, useRef)
- state-management: Redux Toolkit, Zustand, React Context, TanStack Query
- api-patterns: Fetch, Axios, Express routes, Next.js API routes

When Claude writes new code, it follows your existing conventions instead of inventing new ones.

If Claude notices files that shouldn't be indexed (like Unity's Library folder, build outputs, or generated files), it can dynamically exclude them:

// Exclude Unity Library folder and generated files index({ action: "exclude", project: "my-unity-game", paths: ["Library/", "Temp/", ".generated.cs"], reason: "Unity build artifacts" })

"Find duplicate code in my project" "Are there any similar functions that could be merged?" "Show me copy-pasted code that should be refactored"

"Find dead code in this project" "What functions are never called?" "Show me unused exports"

User: "Use CodeSeeker to clean up this project" Claude: I'll analyze your codebase for cleanup opportunities. Found 3 duplicate code blocks: - validateEmail() in auth.ts and user.ts (92% similar) - formatDate() appears in 4 files with minor variations - Error handling pattern repeated in api/.ts Found 2 dead code files: - src/utils/legacy-helper.ts (0 imports) - src/services/unused-service.ts (exported but never imported) Would you like me to: 1. Consolidate the duplicate validators into a shared utility? 2. Remove the dead code files?

Tree-sitter parsers install automatically when needed.

The plugin installshooksthat automatically update the index:

You don't need to do anything—the plugin handles sync automatically.

With MCP Server Only (Cursor, Claude Desktop)

- Claude-initiated changes: Claude can callindex({action: "sync"})tool
- Manual changes: Not automatically detected—ask Claude to reindex periodically

- Large codebases (10K+ files) where Claude struggles to find relevant code
- Projects with established patterns you want Claude to follow
- Complex dependency chains across multiple files
- Teams wanting consistent AI-generated code

- Greenfield projects with little existing code
- Single-file scripts
- Projects where you're actively changing architecture

┌──────────────────────────────────────────────────────────┐ │ Claude Code │ │ │ │ │ MCP Protocol │ │ │ │ │ ┌──────────────────────▼──────────────────────────┐ │ │ │ CodeSeeker MCP Server │ │ │ │ ┌─────────────┬─────────────┬────────────────┐ │ │ │ │ │ Vector │ Knowledge │ Coding │ │ │ │ │ │ Search │ Graph │ Standards │ │ │ │ │ │ (SQLite) │ (SQLite) │ (JSON) │ │ │ │ │ └─────────────┴─────────────┴────────────────┘ │ │ │ └─────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────┘

All data stored locally in.codeseeker/. No external services required.

For large teams (100K+ files, shared indexes), server mode supports PostgreSQL + Neo4j. SeeStorage Documentation.

For the complete technical internals — exact scoring formulas, MCP tool schema, graph edge types, RAPTOR threshold logic, pipeline stages, analysis confidence tiers — see theTechnical Architecture Manual.
- Verify npm and npx work:npx -y codeseeker --version
- Check MCP config file syntax (valid JSON, no trailing commas)
- Restart your editor/Claude application completely
- Check that Node.js is installed:node --version(need v18+)

- Integration Guide- How all components connect
- Architecture- Technical deep dive
- CLI Commands- Full command reference

If CodeSeeker is useful to you, considersponsoring the project.

- 📄White paper(open access):https://doi.org/10.5281/zenodo.21726017
- 🧭Start here— method, tools, testimonials:https://pragmaworks.dev
- 🔨The Forge— 2-day hands-on GS workshop for your team:https://forgeworkshop.dev

A local MCP server for AI coding agents. AST-aware indexing, semantic search, and automatic compression. Your agent stops re-reading your entire codebase every session.