Codeseeker

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 with Claude Code, GitHub Copilot (VS Code 1.99+), Cursor, Windsurf, and Claude Desktop. One command to index; the Claude Code plugin keeps it in sync from there.

Built by PragmaWorks as part of Generative Specification — the discipline for building software with AI that doesn't drift. Two sibling MCP servers compose with this one, each solving a different half of the same problem:

They are independent: install one, or all three.

When you stop needing this

CodeSeeker solves a retrieval problem, and that problem is shrinking.

If you run a spec-driven loop with a real harness — a specification precise enough that a stateless model derives from it, and quality gates that verify the result against a live system — or an intent-driven one, your assistant is being handed the structure it would otherwise have to go find. A sentinel tool that routes actions instead of sprawling across a dozen endpoints removes another slice of the searching. Frontier models with better navigation and larger effective context remove more. Past a certain point, semantic search over your own code stops being the bottleneck, and this server becomes something you could uninstall without noticing.

That is the intended outcome, not a defect: a method that works should make its own scaffolding unnecessary. Most teams do not start there, though, and until the process is in place CodeSeeker is the cheaper substitute — one command instead of a discipline.

If you would rather have the process than the substitute, start with the field guide: [Generative Specification — Field Guide (PDF)](https://github.com/jghiringhelli/generative-specification/blob/main/docs/white-paper/GenerativeSpecification_FieldGuide.pdf).

The Problem

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.

How It Works

A 4-stage pipeline runs on every query:

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 powers the graph action, dead-code detection, and graph expansion in every search.

What Makes It Different

What LSP tools can't do:

• *"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

What vector-only search misses:

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

Installation

Recommended: install once, configure once

npm install -g codeseeker

claude mcp add codeseeker --scope user -e CODESEEKER_STORAGE_MODE=embedded -- codeseeker serve --mcp

--scope user makes it available in every project you open, not just the current one.

Why global rather than `npx -y`: on a machine that has never seen the package, npx downloads it and builds native dependencies before the server can answer, which measured 13.7 seconds to a completed MCP handshake. Clients that give up sooner report that as a connection failure. A global install answers in 759 ms — the download happens once, at a moment when you are expecting it to.

npx (no install)

Portable, and fine once the package is cached. Expect a slow first start.

{

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

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

Other editors

npm install -g codeseeker

codeseeker install --vscode # or --cursor, --windsurf, --vs

🔌 Claude Code Plugin

For Claude Code CLI users — adds auto-sync hooks and slash commands:

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

Slash commands: /codeseeker:init, /codeseeker:reindex

☁️ Devcontainers / GitHub Codespaces

{

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

✅ Verify

Ask your AI assistant: *"What CodeSeeker tools do you have?"*

You should see a single tool named codeseeker. That is intentional: one tool with an action routing key keeps per-request token overhead low (ADR-002). The actions are search, sym, graph, analyze and index.

Advanced Installation Options

📋 MCP Configuration by client

The MCP config JSON is the same for all clients — only the file location differs:

{

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

🖥️ CLI Standalone Usage (without AI assistant)

npm install -g codeseeker

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

What You Get

CodeSeeker exposes one MCP tool, codeseeker. You pick behaviour with action and fill only the matching nested parameter group:

codeseeker({ action, project, search?|sym?|graph?|analyze?|index? })

Always pass project (the absolute project root) — an MCP server cannot detect your working directory.

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

How Indexing Works

You do not have to index anything first. Searching a project CodeSeeker has never seen starts the index automatically and says so. Indexing runs in the background, so the call returns at once rather than blocking your assistant:

User: "Find the authentication logic"

│ ▼ ┌──────────────