Graph-powered code intelligence for Claude Code. Semantic search + knowledge graph for better AI code understanding.
npm install codeseekernpm, not the VS Code marketplace. It's an MCP server that enhances AI assistants, not a standalone extension.
bash
curl -fsSL https://raw.githubusercontent.com/jghiringhelli/codeseeker/master/scripts/install.sh | sh
`
Windows (PowerShell):
`powershell
irm https://raw.githubusercontent.com/jghiringhelli/codeseeker/master/scripts/install.ps1 | iex
`
Restart your IDE and you're done!
$3
Linux (Snap) - All Distributions:
`bash
sudo snap install codeseeker --classic
codeseeker install --vscode # or --cursor, --windsurf
`
macOS/Linux (Homebrew):
`bash
brew install jghiringhelli/codeseeker/codeseeker
codeseeker install --vscode # or --cursor, --windsurf
`
Windows (Chocolatey):
`powershell
choco install codeseeker
codeseeker install --vscode # or --cursor, --windsurf
`
Cross-platform (npm):
`bash
npm install -g codeseeker
codeseeker install --vscode # or --cursor, --windsurf
`
$3
Run without installing:
`bash
npx codeseeker init
npx codeseeker -c "how does authentication work?"
`
$3
If you use Claude Code CLI, you can install as a plugin:
`bash
/plugin install codeseeker@github:jghiringhelli/codeseeker#plugin
`
This gives you auto-sync hooks and slash commands (/codeseeker:init, /codeseeker:reindex).
$3
CodeSeeker auto-installs in devcontainers! Just add .devcontainer/devcontainer.json:
`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).
$3
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
π Manual MCP Configuration (if auto-install doesn't work)
$3
Add to .vscode/mcp.json in your project:
`json
{
"mcpServers": {
"codeseeker": {
"command": "npx",
"args": ["-y", "codeseeker", "serve", "--mcp"],
"env": {
"CODESEEKER_STORAGE_MODE": "embedded"
}
}
}
}
`
$3
Add to .cursor/mcp.json in your project:
`json
{
"mcpServers": {
"codeseeker": {
"command": "npx",
"args": ["-y", "codeseeker", "serve", "--mcp"],
"env": {
"CODESEEKER_STORAGE_MODE": "embedded"
}
}
}
}
`
$3
Add to your claude_desktop_config.json:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
`json
{
"mcpServers": {
"codeseeker": {
"command": "npx",
"args": ["-y", "codeseeker", "serve", "--mcp"],
"env": {
"CODESEEKER_STORAGE_MODE": "embedded"
}
}
}
}
`
$3
`bash
Apply to all projects (user-level)
codeseeker install --vscode --global
Apply to current project only
codeseeker install --vscode
`
π₯οΈ CLI Standalone Usage (without AI assistant)
`bash
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) |
| 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) |
$3
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:
`json
{
"validation": {
"email": {
"preferred": "z.string().email()",
"usage_count": 12,
"files": ["src/auth.ts", "src/user.ts"]
}
},
"react-patterns": {
"state": {
"preferred": "useState()",
"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:
`typescript
// 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.
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
$3
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.
$3
- Claude-initiated changes: Claude can call notify_file_changes tool
- Manual changes: Not automatically detectedβask Claude to reindex periodically
$3
| 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
$3
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
$3
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+)
$3
First-time indexing of large projects (50K+ files) can take 5+ minutes. Subsequent uses are instant.
$3
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
$3
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.