{
"markdown": "# CodeSeeker\n\n**Four-layer hybrid search and knowledge graph for AI coding assistants.** \nBM25 + 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.\n\n[](https://www.npmjs.com/package/codeseeker)\n[](LICENSE)\n[](https://www.typescriptlang.org/)\n\nWorks with **Claude Code**, **GitHub Copilot** (VS Code 1.99+), **Cursor**, **Windsurf**, and **Claude Desktop**. \nZero configuration — indexes on first use, stays in sync automatically.\n\n## The Problem\n\nAI assistants are powerful editors, but they navigate code like a tourist:\n- **Grep finds text** — not meaning. `\"find authentication logic\"` returns every file containing the word \"auth\"\n- **File reads are isolated** — Claude sees a file but not its dependencies, callers, or the patterns your team established\n- **No memory of your project** — every session starts from scratch\n\nCodeSeeker fixes this. It indexes your codebase once and gives AI assistants a queryable knowledge graph they can use on every turn.\n\n## How It Works\n\nA 4-stage pipeline runs on every query:\n\n```\nQuery: \"find JWT refresh token logic\"\n │\n ▼ Stage 1 — Hybrid retrieval\n ┌─────────────────────────────────────────────────────┐\n │ BM25 (exact symbols, camelCase tokenized) │\n │ + │\n │ Vector search (384-dim Xenova embeddings) │\n │ ↓ │\n │ Reciprocal Rank Fusion: score = Σ 1/(60 + rank_i) │\n │ Top-30 results, including RAPTOR directory nodes │\n └─────────────────────────────────────────────────────┘\n │\n ▼ Stage 2 — RAPTOR cascade (conditional)\n ┌─────────────────────────────────────────────────────┐\n │ IF best directory-summary score ≥ 0.5: │\n │ → narrow results to that directory automatically │\n │ ELSE: all 30 results pass through unchanged │\n │ Effect: \"what does auth/ do?\" scopes to auth/ │\n │ \"jwt.ts decode function\" bypasses this │\n └─────────────────────────────────────────────────────┘\n │\n ▼ Stage 3 — Scoring and deduplication\n ┌─────────────────────────────────────────────────────┐\n │ Dedup: keep highest-score chunk per file │\n │ Source files: +0.10 (definition sites matter) │\n │ Test files: −0.15 (prevent test dominance) │\n │ Symbol boost: +0.20 (query token in filename) │\n │ Multi-chunk: up to +0.30 (file has many hits) │\n └─────────────────────────────────────────────────────┘\n │\n ▼ Stage 4 — Graph expansion\n ┌─────────────────────────────────────────────────────┐\n │ Top-10 results → follow IMPORTS/CALLS/EXTENDS edges │\n │ Structural neighbors scored at source × 0.7 │\n │ Avg graph connectivity: 20.8 edges/node │\n └─────────────────────────────────────────────────────┘\n │\n ▼\n auth/jwt.ts (0.94), auth/refresh.ts (0.89), ...\n```\n\nThe knowledge graph is built from AST-parsed imports at index time. It's what powers `analyze dependencies`, dead-code detection, and graph expansion in every search.\n\n## What Makes It Different\n\n| Approach | Strengths | Limitations |\n|----------|-----------|-------------|\n| **Grep / ripgrep** | Fast, universal | No semantic understanding |\n| **Vector search only** | Finds similar code | Misses structural relationships |\n| **Serena** | Precise LSP symbol navigation, 30+ languages | No semantic search, no cross-file reasoning |\n| **Codanna** | Fast symbol lookup, good call graphs | Semantic search needs JSDoc — undocumented code gets no embeddings; no BM25, no RAPTOR, Windows experimental |\n| **CodeSeeker** | BM25 + embedding fusion + RAPTOR + graph + coding standards + multi-language AST | Requires initial indexing (30s–5min) |\n\n**What LSP tools can't do:**\n- *\"Find code that handles errors like this\"* → semantic pattern search\n- *\"What validation approach does this project use?\"* → auto-detected coding standards\n- *\"Show me everything related to authentication\"* → graph traversal across indirect dependencies\n\n**What vector-only search misses:**\n- Direct import/export chains\n- Class inheritance hierarchies\n- Which files actually depend on which\n\n## Installation\n\n### Recommended: npx (no install needed)\n\nThe standard way to configure any MCP server — no global install required:\n\n```json\n{\n \"mcpServers\": {\n \"codeseeker\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"codeseeker\", \"serve\", \"--mcp\"]\n }\n }\n}\n```\n\nAdd this to your MCP config file ([see below](#advanced-installation-options) for per-client locations) and restart your editor.\n\n### npm global install\n\n```bash\nnpm install -g codeseeker\ncodeseeker install --vscode # or --cursor, --windsurf\n```\n\n### 🔌 Claude Code Plugin\n\nFor Claude Code CLI users — adds auto-sync hooks and slash commands:\n\n```bash\n/plugin install codeseeker@github:jghiringhelli/codeseeker#plugin\n```\n\nSlash commands: `/codeseeker:init`, `/codeseeker:reindex`\n\n### ☁️ Devcontainers / GitHub Codespaces\n\n```json\n{\n \"name\": \"My Project\",\n \"image\": \"mcr.microsoft.com/devcontainers/javascript-node:18\",\n \"postCreateCommand\": \"npm install -g codeseeker && codeseeker install --vscode\"\n}\n```\n\n### ✅ Verify\n\nAsk your AI assistant: *\"What CodeSeeker tools do you have?\"*\n\nYou should see: `search`, `analyze`, `index` — CodeSeeker's three tools.\n\n## Advanced Installation Options\n\n\n📋 MCP Configuration by client
\n\nThe MCP config JSON is the same for all clients — only the file location differs:\n\n| Client | Config file |\n|--------|------------|\n| **VS Code** (Claude Code / Copilot) | `.vscode/mcp.json` in your project, or `~/.vscode/mcp.json` globally |\n| **Cursor** | `.cursor/mcp.json` in your project |\n| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows) |\n| **Windsurf** | `.windsurf/mcp.json` in your project |\n\n```json\n{\n \"mcpServers\": {\n \"codeseeker\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"codeseeker\", \"serve\", \"--mcp\"]\n }\n }\n}\n```\n\n \n\n\n🖥️ CLI Standalone Usage (without AI assistant)
\n\n```bash\nnpm install -g codeseeker\ncd your-project\ncodeseeker init\ncodeseeker -c \"how does authentication work in this project?\"\n```\n\n \n\n## What You Get\n\nOnce configured, Claude has access to these MCP tools (used automatically):\n\n| Tool | Actions / Usage | What It Does |\n|------|-----------------|-------------|\n| `search` | `{query}` | Hybrid search: vector + BM25 text + path-match, fused with RRF; RAPTOR directory summaries surface for abstract queries |\n| `search` | `{query, search_type: \"graph\"}` | Hybrid search **+ Graph RAG** — follows import/call/extends edges to surface structurally connected files |\n| `search` | `{query, search_type: \"vector\"}` | Pure embedding cosine-similarity search (no BM25 or path scoring) |\n| `search` | `{query, search_type: \"fts\"}` | Pure BM25 text search with CamelCase tokenisation and synonym expansion |\n| `search` | `{query, read: true}` | Search + read file contents in one step |\n| `search` | `{filepath}` | Read a file with its related code automatically included |\n| `analyze` | `{action: \"dependencies\", filepath}` | Traverse the knowledge graph (imports, calls, extends) |\n| `analyze` | `{action: \"standards\"}` | Your project's detected patterns (validation, error handling) |\n| `analyze` | `{action: \"duplicates\"}` | Find duplicate/similar code blocks across your codebase |\n| `analyze` | `{action: \"dead_code\"}` | Detect unused exports, functions, and classes |\n| `index` | `{action: \"init\", path}` | Manually trigger indexing (rarely needed) |\n| `index` | `{action: \"sync\", changes}` | Update index for specific files |\n| `index` | `{action: \"exclude\", paths}` | Dynamically exclude/include files from the index |\n| `index` | `{action: \"status\"}` | List indexed projects with file/chunk counts |\n\n**You don't invoke these manually**—Claude uses them automatically when searching code or analyzing relationships.\n\n## How Indexing Works\n\n**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.\n\n```\nUser: \"Find the authentication logic\"\n │\n ▼\n┌─────────────────────────────────────┐\n│ Claude calls search({query: ...}) │\n│ │ │\n│ ▼ │\n│ Project indexed? ──No──► Index now │\n│ │ (auto) │\n│ Yes │ │\n│ │◀───────────────────┘ │\n│ ▼ │\n│ Return search results │\n└─────────────────────────────────────┘\n```\n\nFirst search on a new project takes 30 seconds to several minutes (depending on size). Subsequent searches are instant.\n\n---\n\n## Search Quality Research\n\n\n📊 Component ablation study (v2.0.0) — measured impact of each retrieval layer
\n\n### Setup\n\n18 hand-labelled queries across two real-world codebases:\n\n| Corpus | Language | Files | Queries | Query types |\n|--------|----------|-------|---------|-------------|\n| [Conclave](https://github.com/jghiringhelli/conclave) | TypeScript (pnpm monorepo) | 201 | 10 | Symbol lookup, cross-file chains, out-of-scope |\n| [ImperialCommander2](https://github.com/jonwill8/ImperialCommander2) | C# / Unity | 199 | 8 | Class lookup, controller wiring, file I/O |\n\nEach query has one or more `mustFind` targets (exact file basenames) and optional `mustNotFind` targets (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.\n\nMetrics: **MRR** (Mean Reciprocal Rank), **P@1** (Precision at 1), **R@5** (Recall at 5), **F1@3**.\n\n### Ablation results\n\n| Configuration | MRR | P@1 | P@3 | R@5 | F1@3 | Notes |\n|--------------|-----|-----|-----|-----|------|-------|\n| **Hybrid baseline** (BM25 + embed + RAPTOR, no graph) | **75.2%** | 61.1% | 29.6% | 91.7% | 44.4% | Production default |\n| + graph 1-hop | 74.9% | 61.1% | 29.6% | 91.7% | 44.4% | ±0% ranking, adds structural neighbors |\n| + graph 2-hop | 74.9% | 61.1% | 29.6% | 91.7% | 44.4% | Scope leaks on unrelated queries |\n| No RAPTOR (graph 1-hop) | 74.9% | 61.1% | 29.6% | 91.7% | 44.4% | RAPTOR contributes +0.3% |\n\n### What each layer actually does\n\n**BM25 + embedding fusion (RRF)** \nThe 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.\n\n**RAPTOR (hierarchical directory summaries)** \nGenerates 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% MRR** on symbol queries. Fires conservatively — only when the directory is an obvious match. Its real value is on _abstract 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.\n\n**Knowledge graph (import/dependency edges)** \nAverage connectivity: 20.8 file→file edges per node across both TS and C# codebases. Measured ranking impact: **±0% MRR** for 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: the `analyze dependencies` action and explicit `graph` search type give Claude traversable import chains, inheritance hierarchies, and dependency paths that embeddings alone cannot provide.\n\n**Type boost / penalty scoring** \nSource files get +0.10 score boost; test files get −0.15 penalty; lock files and docs get −0.05 penalty. Without this, `integration.test.ts` would rank above `dag-engine.ts` for exact symbol queries because test files import and exercise every symbol in the source. The penalty corrects this without eliminating test files from results.\n\n**Monorepo directory exclusion fix** \nThe single highest-impact change in v1.12.0: removing `packages/` from the default exclusion list. For pnpm/yarn/lerna monorepos where all source lives under `packages/`, this exclusion was silently dropping all source files. Effect: **10% → 72% MRR** on the Conclave monorepo benchmark.\n\n### Known limitations\n\n| Query | Target | Issue | Root cause |\n|-------|--------|-------|-----------|\n| `cv-prompts` | `orchestrator.ts` | rank 97+ even with 2-hop graph | `prompt-builder.test.ts` outscores `prompt-builder.ts` semantically; source file never enters top-10, so we can't graph-walk from it to `orchestrator.ts`. Test-file dominance on cross-file queries. |\n| `cv-exec-mode` | `types.ts` | rank 11–12 | `types.ts` is a pure type-export file; low keyword density. Found within R@5 (rank ≤ 15). |\n\n### Benchmark script\n\nReproduce with:\n```bash\nnpm run build\nnode scripts/real-bench.js\n```\n\nRequires `C:\\workspace\\claude\\conclave` and `C:\\workspace\\ImperialCommander2` to be present locally (or update paths in `scripts/real-bench.js`).\n\n \n\n## Auto-Detected Coding Standards\n\nCodeSeeker analyzes your codebase and extracts patterns:\n\n```json\n{\n \"validation\": {\n \"email\": {\n \"preferred\": \"z.string().email()\",\n \"usage_count\": 12,\n \"files\": [\"src/auth.ts\", \"src/user.ts\"]\n }\n },\n \"react-patterns\": {\n \"state\": {\n \"preferred\": \"useState()\",\n \"usage_count\": 45\n }\n }\n}\n```\n\nDetected pattern categories:\n- **validation**: Zod, Yup, Joi, validator.js, custom regex\n- **error-handling**: API error responses, try-catch patterns, custom Error classes\n- **logging**: Console, Winston, Bunyan, structured logging\n- **testing**: Jest/Vitest setup, assertion patterns\n- **react-patterns**: Hooks (useState, useEffect, useMemo, useCallback, useRef)\n- **state-management**: Redux Toolkit, Zustand, React Context, TanStack Query\n- **api-patterns**: Fetch, Axios, Express routes, Next.js API routes\n\nWhen Claude writes new code, it follows your existing conventions instead of inventing new ones.\n\n## Managing Index Exclusions\n\nIf Claude notices files that shouldn't be indexed (like Unity's Library folder, build outputs, or generated files), it can dynamically exclude them:\n\n```\n// Exclude Unity Library folder and generated files\nindex({\n action: \"exclude\",\n project: \"my-unity-game\",\n paths: [\"Library/**\", \"Temp/**\", \"*.generated.cs\"],\n reason: \"Unity build artifacts\"\n})\n```\n\nExclusions are persisted in `.codeseeker/exclusions.json` and automatically respected during reindexing.\n\n## Code Cleanup Tools\n\nCodeSeeker helps you maintain a clean codebase by finding duplicate code and detecting dead code.\n\n### Finding Duplicate Code\n\nAsk Claude to find similar code blocks that could be consolidated:\n\n```\n\"Find duplicate code in my project\"\n\"Are there any similar functions that could be merged?\"\n\"Show me copy-pasted code that should be refactored\"\n```\n\nCodeSeeker uses vector similarity to find semantically similar code—not just exact matches. It detects:\n- Copy-pasted functions with minor variations\n- Similar validation logic across files\n- Repeated patterns that could be extracted into utilities\n\n### Finding Dead Code\n\nAsk Claude to identify unused code that can be safely removed:\n\n```\n\"Find dead code in this project\"\n\"What functions are never called?\"\n\"Show me unused exports\"\n```\n\nCodeSeeker analyzes the knowledge graph to find:\n- Exported functions/classes that are never imported\n- Internal functions with no callers\n- Orphaned files with no incoming dependencies\n\n**Example workflow:**\n```\nUser: \"Use CodeSeeker to clean up this project\"\n\nClaude: I'll analyze your codebase for cleanup opportunities.\n\nFound 3 duplicate code blocks:\n- validateEmail() in auth.ts and user.ts (92% similar)\n- formatDate() appears in 4 files with minor variations\n- Error handling pattern repeated in api/*.ts\n\nFound 2 dead code files:\n- src/utils/legacy-helper.ts (0 imports)\n- src/services/unused-service.ts (exported but never imported)\n\nWould you like me to:\n1. Consolidate the duplicate validators into a shared utility?\n2. Remove the dead code files?\n```\n\n## Language Support\n\n| Language | Parser | Relationship Extraction |\n|----------|--------|------------------------|\n| TypeScript/JavaScript | Babel AST | Excellent |\n| Python | Tree-sitter | Excellent |\n| Java | Tree-sitter | Excellent |\n| C# | Regex | Good |\n| Go | Regex | Good |\n| Rust, C/C++, Ruby, PHP | Regex | Basic |\n\nTree-sitter parsers install automatically when needed.\n\n## Keeping the Index in Sync\n\n### With Claude Code Plugin\n\nThe plugin installs **hooks** that automatically update the index:\n\n| Event | What Happens |\n|-------|--------------|\n| Claude edits a file | Index updated automatically |\n| Claude runs `git pull/checkout/merge` | Full reindex triggered |\n| You run `/codeseeker:reindex` | Manual full reindex |\n\n**You don't need to do anything**—the plugin handles sync automatically.\n\n### With MCP Server Only (Cursor, Claude Desktop)\n\n- **Claude-initiated changes**: Claude can call `index({action: \"sync\"})` tool\n- **Manual changes**: Not automatically detected—ask Claude to reindex periodically\n\n### Sync Summary\n\n| Setup | Claude Edits | Git Operations | Manual Edits |\n|-------|--------------|----------------|--------------|\n| **Plugin** (Claude Code) | Auto | Auto | Manual |\n| **MCP** (Cursor, Desktop) | Ask Claude | Ask Claude | Ask Claude |\n| **CLI** | Auto | Auto | Manual |\n\n## When CodeSeeker Helps Most\n\n**Good fit:**\n- Large codebases (10K+ files) where Claude struggles to find relevant code\n- Projects with established patterns you want Claude to follow\n- Complex dependency chains across multiple files\n- Teams wanting consistent AI-generated code\n\n**Less useful:**\n- Greenfield projects with little existing code\n- Single-file scripts\n- Projects where you're actively changing architecture\n\n## Architecture\n\n```\n┌──────────────────────────────────────────────────────────┐\n│ Claude Code │\n│ │ │\n│ MCP Protocol │\n│ │ │\n│ ┌──────────────────────▼──────────────────────────┐ │\n│ │ CodeSeeker MCP Server │ │\n│ │ ┌─────────────┬─────────────┬────────────────┐ │ │\n│ │ │ Vector │ Knowledge │ Coding │ │ │\n│ │ │ Search │ Graph │ Standards │ │ │\n│ │ │ (SQLite) │ (SQLite) │ (JSON) │ │ │\n│ │ └─────────────┴─────────────┴────────────────┘ │ │\n│ └─────────────────────────────────────────────────┘ │\n└──────────────────────────────────────────────────────────┘\n```\n\nAll data stored locally in `.codeseeker/`. No external services required.\n\nFor large teams (100K+ files, shared indexes), server mode supports PostgreSQL + Neo4j. See [Storage Documentation](docs/technical/storage.md).\n\nFor the complete technical internals — exact scoring formulas, MCP tool schema, graph edge types, RAPTOR threshold logic, pipeline stages, analysis confidence tiers — see the **[Technical Architecture Manual](docs/technical/architecture.md)**.\n\n## Troubleshooting\n\n### MCP server not connecting\n\n1. Verify npm and npx work: `npx -y codeseeker --version`\n2. Check MCP config file syntax (valid JSON, no trailing commas)\n3. Restart your editor/Claude application completely\n4. Check that Node.js is installed: `node --version` (need v18+)\n\n### Indexing seems slow\n\nFirst-time indexing of large projects (50K+ files) can take 5+ minutes. Subsequent uses are instant.\n\n### Tools not appearing in Claude\n\n1. Ask Claude: *\"What CodeSeeker tools do you have?\"*\n2. If no tools appear, check MCP config file exists and has correct syntax\n3. Restart your IDE completely (not just reload window)\n4. Check Claude/Copilot MCP connection status in IDE\n\n### Still stuck?\n\nOpen an issue: [GitHub Issues](https://github.com/jghiringhelli/codeseeker/issues)\n\n## Documentation\n\n- [Integration Guide](docs/INTEGRATION.md) - How all components connect\n- [Architecture](docs/technical/architecture.md) - Technical deep dive\n- [CLI Commands](docs/install/cli_commands_manual.md) - Full command reference\n\n## Supported Platforms\n\n| Client | MCP Support | Config |\n|--------|-------------|--------|\n| **Claude Code** (VS Code) | ✅ | `.vscode/mcp.json` or plugin |\n| **GitHub Copilot** (VS Code 1.99+) | ✅ | `.vscode/mcp.json` |\n| **Cursor** | ✅ | `.cursor/mcp.json` |\n| **Windsurf** | ✅ | `.windsurf/mcp.json` |\n| **Claude Desktop** | ✅ | `claude_desktop_config.json` |\n| **Visual Studio** | ✅ | `codeseeker install --vs` |\n\n> Claude Code and GitHub Copilot share the same `.vscode/mcp.json` — configure once, works for both.\n\n## Support\n\nIf CodeSeeker is useful to you, consider [sponsoring the project](https://github.com/sponsors/jghiringhelli).\n\n## License\n\nMIT License. See [LICENSE](LICENSE).\n\n---\n\n*CodeSeeker gives Claude the code understanding that grep and embeddings alone can't provide.*\n\n\n---\n\n## Part of Generative Specification\n\nA free tool behind **Generative Specification (GS)** — the discipline for building software with AI that doesn't drift: you author a specification precise enough that a stateless AI derives correct code from it, and a harness verifies it against a live system.\n\n- 📄 **White paper** (open access): https://doi.org/10.5281/zenodo.21726017\n- 🧭 **Start here** — method, tools, testimonials: https://pragmaworks.dev\n- 🔨 **The Forge** — 2-day hands-on GS workshop for your team: https://forgeworkshop.dev\n",
"bytes": 22189,
"sha": "6f5018819229f14ff338233daf23f917fd0ba94c500c8ebd5ce378ebac5b6d41",
"repo_slug": "jghiringhelli/codeseeker",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_jghiringhelli_codeseeker_60206ee5/readme"
}