CodeSeeker

Graph-powered code intelligence for Claude Code. CodeSeeker builds a knowledge graph of your codebase—not just embeddings—so Claude understands how your code actually connects.

What is CodeSeeker? An MCP server that gives AI assistants semantic code search and knowledge graph traversal. Works with Claude Code, GitHub Copilot, Cursor, and Claude Desktop.

⚠️ NOT A VS CODE EXTENSION: CodeSeeker is installed via npm, not the VS Code marketplace. It's an MCP server that enhances AI assistants, not a standalone extension.

Installation

🚨 Important: CodeSeeker is NOT a VS Code extension. It's an MCP server (Model Context Protocol) that works WITH AI assistants like Claude Code and GitHub Copilot. Don't look for it in the VS Code marketplace—install via the methods below.

⚡ One-Line Install (Easiest)

Copy/paste ONE command - auto-detects your system and configures everything:

macOS/Linux:

curl -fsSL https://raw.githubusercontent.com/jghiringhelli/codeseeker/master/scripts/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/jghiringhelli/codeseeker/master/scripts/install.ps1 | iex

Restart your IDE and you're done!

📦 Package Managers (Advanced)

Linux (Snap) - All Distributions:

sudo snap install codeseeker
codeseeker install --vscode      # or --cursor, --windsurf

⚠️ Snap limitation: Due to strict confinement, the snap can only access projects in your home directory (~/). For projects outside ~/, use npm or Homebrew instead.

macOS/Linux (Homebrew):

brew install jghiringhelli/codeseeker/codeseeker
codeseeker install --vscode      # or --cursor, --windsurf

Windows (Chocolatey):

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

Cross-platform (npm):

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

🚀 No Install Required (npx)

Run without installing:

npx codeseeker init
npx codeseeker -c "how does authentication work?"

🔌 Claude Code Plugin

If you use Claude Code CLI, you can install as a plugin:

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

This gives you auto-sync hooks and slash commands (/codeseeker:init, /codeseeker:reindex).

☁️ Devcontainer / GitHub Codespaces

CodeSeeker auto-installs in devcontainers! Just add .devcontainer/devcontainer.json:

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

Or use our pre-configured devcontainer (already included in this repo).

✅ Verify Installation

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

You should see: search, search_and_read, show_dependencies, read_with_context, standards, etc.

---

The Problem

Claude Code is powerful, but it navigates your codebase like a tourist with a phrasebook:

• Grep searches find text matches, not semantic meaning
• File reads show code in isolation, missing the bigger picture
• No memory of your project's patterns—every session starts fresh

The result? Claude asks you to explain code relationships it should already know. It writes validation logic that doesn't match your existing patterns. It misses dependencies and breaks things.

How CodeSeeker Fixes This

CodeSeeker builds a knowledge graph of your codebase:

┌─────────────┐     imports      ┌─────────────┐
│  auth.ts    │ ───────────────▶ │  user.ts    │
└─────────────┘                  └─────────────┘
       │                                │
       │ calls                          │ extends
       ▼                                ▼
┌─────────────┐     implements   ┌─────────────┐
│ session.ts  │ ◀─────────────── │ BaseUser.ts │
└─────────────┘                  └─────────────┘

When you ask "add password reset to authentication", Claude doesn't just find files containing "auth"—it traverses the graph to find:

• What auth.ts imports and exports
• Which services call authentication functions
• What patterns exist in related code
• How your project handles similar flows

This is Graph RAG (Retrieval-Augmented Generation), not just vector search.

Advanced Installation Options

VS Code (Claude Code & GitHub Copilot)

Add to .vscode/mcp.json in your project:

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

Cursor

Add to .cursor/mcp.json in your project:

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

Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Global vs Project-Level Configuration

# Apply to all projects (user-level)
codeseeker install --vscode --global

# Apply to current project only
codeseeker install --vscode

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

What You Get

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

Tool	What It Does
search_code	Hybrid search: vector + text + path with RRF fusion
find_and_read	Search + Read in one step - returns file content directly
get_code_relationships	Traverse the knowledge graph (imports, calls, extends)
get_file_context	Read a file with its related code automatically included
get_coding_standards	Your project's detected patterns (validation, error handling)
find_duplicates	Find duplicate/similar code blocks across your codebase
find_dead_code	Detect unused exports, functions, and classes
index_project	Manually trigger indexing (rarely needed)
notify_file_changes	Update index for specific files
manage_index	Dynamically exclude/include files from the index

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

How Indexing Works

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_code()          │
│         │                           │
│         ▼                           │
│ 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.

What Makes It Different

Approach	How It Works	Strengths	Limitations
Grep/ripgrep	Text pattern matching	Fast, universal	No semantic understanding
Vector search only	Embedding similarity	Finds similar code	Misses structural relationships
LSP-based tools	Language server protocol	Precise symbol definitions	No semantic search, no cross-file reasoning
CodeSeeker	Knowledge graph + hybrid search	Semantic + structure + patterns	Requires initial indexing (30s-5min)

CodeSeeker's Unique Capabilities

What LSP tools can't do:

• "Find code that handles errors like this" → Semantic search finds similar patterns
• "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 relationships
• Class inheritance chains
• Function call graphs
• Which files actually depend on which

CodeSeeker combines all three: graph traversal for structure, vector search for meaning, text search for precision—fused with Reciprocal Rank Fusion (RRF) for optimal results.

Auto-Detected Coding Standards

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

Detected pattern categories:

• 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.

Managing Index Exclusions

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
manage_index({
  action: "exclude",
  project: "my-unity-game",
  paths: ["Library/**", "Temp/**", "*.generated.cs"],
  reason: "Unity build artifacts"
})

Exclusions are persisted in .codeseeker/exclusions.json and automatically respected during reindexing.

Code Cleanup Tools

CodeSeeker helps you maintain a clean codebase by finding duplicate code and detecting dead code.

Finding Duplicate Code

Ask Claude to find similar code blocks that could be consolidated:

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

CodeSeeker uses vector similarity to find semantically similar code—not just exact matches. It detects:

• Copy-pasted functions with minor variations
• Similar validation logic across files
• Repeated patterns that could be extracted into utilities

Finding Dead Code

Ask Claude to identify unused code that can be safely removed:

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

CodeSeeker analyzes the knowledge graph to find:

• Exported functions/classes that are never imported
• Internal functions with no callers
• Orphaned files with no incoming dependencies

Example workflow:

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?

Language Support

Language	Parser	Relationship Extraction
TypeScript/JavaScript	Babel AST	Excellent
Python	Tree-sitter	Excellent
Java	Tree-sitter	Excellent
C#	Regex	Good
Go	Regex	Good
Rust, C/C++, Ruby, PHP	Regex	Basic

Tree-sitter parsers install automatically when needed.

Keeping the Index in Sync

With Claude Code Plugin

The plugin installs hooks that automatically update the index:

Event	What Happens
Claude edits a file	Index updated automatically
Claude runs git pull/checkout/merge	Full reindex triggered
You run /codeseeker:reindex	Manual full reindex

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

With MCP Server Only (Cursor, Claude Desktop)

• Claude-initiated changes: Claude can call notify_file_changes tool
• Manual changes: Not automatically detected—ask Claude to reindex periodically

Sync Summary

Setup	Claude Edits	Git Operations	Manual Edits
Plugin (Claude Code)	Auto	Auto	Manual
MCP (Cursor, Desktop)	Ask Claude	Ask Claude	Ask Claude
CLI	Auto	Auto	Manual

When CodeSeeker Helps Most

Good fit:

• 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

Less useful:

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

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. See Storage Documentation.

Troubleshooting

"I can't find CodeSeeker in the VS Code marketplace"

CodeSeeker is NOT a VS Code extension. It's an MCP server that works WITH AI assistants.

✅ Correct: Install via npm: npm install -g codeseeker ❌ Wrong: Looking for it in VS Code Extensions marketplace

MCP server not connecting

1. Verify npm and npx work: npx -y codeseeker --version
2. Check MCP config file syntax (valid JSON, no trailing commas)
3. Restart your editor/Claude application completely
4. Check that Node.js is installed: node --version (need v18+)

Indexing seems slow

First-time indexing of large projects (50K+ files) can take 5+ minutes. Subsequent uses are instant.

Tools not appearing in Claude

1. Ask Claude: "What CodeSeeker tools do you have?"
2. If no tools appear, check MCP config file exists and has correct syntax
3. Restart your IDE completely (not just reload window)
4. Check Claude/Copilot MCP connection status in IDE

Still stuck?

Open an issue: GitHub Issues

Documentation

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

Supported Platforms

Platform	MCP Support	Install Command
Claude Code (VS Code)	Yes	codeseeker install --vscode or plugin
GitHub Copilot (VS Code)	Yes (VS Code 1.99+)	codeseeker install --vscode
Cursor	Yes	codeseeker install --cursor
Claude Desktop	Yes	Manual config
Windsurf	Yes	codeseeker install --windsurf
Visual Studio	Yes	codeseeker install --vs

Note: Claude Code and GitHub Copilot both run in VS Code and share the same MCP configuration (.vscode/mcp.json). The flags --vscode, --claude-code, and --copilot are interchangeable.

Support

If CodeSeeker is useful to you, consider sponsoring the project.

License

MIT License. See LICENSE.

---

CodeSeeker gives Claude the code understanding that grep and embeddings alone can't provide.