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.

[![npm version](https://img.shields.io/npm/v/codeseeker.svg)](https://www.npmjs.com/package/codeseeker)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![TypeScript](https://img.shields.io/badge/TypeScript-100%25-blue.svg)](https://www.typescriptlang.org/)

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.

## 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

| Approach | Strengths | Limitations |
|----------|-----------|-------------|
| **Grep / ripgrep** | Fast, universal | No semantic understanding |
| **Vector search only** | Finds similar code | Misses structural relationships |
| **Serena** | Precise LSP symbol navigation, 30+ languages | No semantic search, no cross-file reasoning |
| **Codanna** | Fast symbol lookup, good call graphs | Semantic search needs JSDoc — undocumented code gets no embeddings; no BM25, no RAPTOR, Windows experimental |
| **CodeSeeker** | BM25 + embedding fusion + RAPTOR + graph + coding standards + multi-language AST | Requires initial indexing (30s–5min) |

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

```bash
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.

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

Add this to your MCP config file ([see below](#advanced-installation-options) for per-client locations) and restart your editor.

### Other editors

```bash
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:

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

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

### ☁️ Devcontainers / GitHub Codespaces

```json
{
  "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

<details>
<summary><b>📋 MCP Configuration by client</b></summary>

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

| Client | Config file |
|--------|------------|
| **VS Code** (Claude Code / Copilot) | `.vscode/mcp.json` in your project, or `~/.vscode/mcp.json` globally |
| **Cursor** | `.cursor/mcp.json` in your project |
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
| **Windsurf** | `.windsurf/mcp.json` in your project |

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

</details>

<details>
<summary><b>🖥️ CLI Standalone Usage</b> (without AI assistant)</summary>

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

</details>

## What You Get

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

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

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

| action | Parameters | What It Does |
|---|---|---|
| `search` | `search:{q}` | Hybrid search: BM25 + vector embeddings fused with RRF, then graph expansion; RAPTOR directory summaries surface for abstract queries |
| `search` | `search:{q, type:"vector"}` | Pure embedding cosine-similarity search |
| `search` | `search:{q, type:"fts"}` | Pure BM25 text search with CamelCase tokenisation |
| `search` | `search:{q, full:true}` | Include a code snippet with each result (default: summaries only) |
| `search` | `search:{q, exists:true}` | Quick yes/no — returns `{found, count, top_file}` |
| `sym` | `sym:{name}` | Look up a class/function by name and show its graph neighbours |
| `graph` | `graph:{seed, depth, rel, dir}` | Traverse the knowledge graph from a file (imports, calls, extends) |
| `graph` | `graph:{q}` | Same, but find the seed files semantically first |
| `analyze` | `analyze:{kind:"standards"}` | Your project's detected patterns (validation, error handling) |
| `analyze` | `analyze:{kind:"duplicates"}` | Find duplicate/similar code blocks |
| `analyze` | `analyze:{kind:"dead_code"}` | Detect unused exports, orphaned files, coupling issues |
| `index` | `index:{op:"init", path}` | Build the index for a project (required once — see below) |
| `index` | `index:{op:"sync", changes}` | Update the index for specific files |
| `index` | `index:{op:"exclude", paths}` | Exclude/include paths from the index |
| `index` | `index:{op:"status"}` | List indexed projects with file/chunk counts |
| `index` | `index:{op:"parsers"}` | List/install Tree-sitter parsers |

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

## How Indexing Works

**A project must be indexed once before search works.** CodeSeeker does not index on
first query — if the project is unknown it returns an error telling you to initialise it.
This is deliberate: silently indexing a large repository inside a tool call would block
the assistant for minutes with no way to cancel.

```
User: "Find the authentication logic"
        │
        ▼
┌─────────────────