Codesearch

codesearch

[](https://opensource.org/licenses/Apache-2.0) [](https://www.rust-lang.org/) [](https://modelcontextprotocol.io/) [](https://github.com/flupkede/codesearch/releases) [](https://github.com/flupkede/codesearch/stargazers)

Multi-repo semantic code search for AI agents — a Rust MCP server with vector + BM25 hybrid retrieval, symbol navigation, and cross-repository orchestration. Fully local, fully offline, no GPU, no Docker.

codesearch gives AI agents (OpenCode, Claude Code, Cursor, and any MCP client) deep codebase understanding through 5 unified MCP tools. Index once, search semantically across multiple repositories simultaneously.

Why codesearch?

• Multi-repo serve mode: Fan-out queries across repository groups with cross-repo RRF ranking
• Hybrid retrieval: Vector embeddings + BM25 full-text search fused with Reciprocal Rank Fusion
• Symbol navigation: Jump to definitions, find usages, trace imports and dependents — in the same tool
• AST-aware chunking: Tree-sitter parsing for 16 languages — chunks align to functions/classes (and Markdown sections), not arbitrary line ranges
• Token-efficient: Returns metadata by default; agents fetch full code only when needed via get_chunk
• Lightweight footprint: Hundreds of MB on disk, runs on CPU only, no runtime model downloads (works behind enterprise proxies)
• Zero config for single repos: codesearch index && codesearch mcp — done

How does this compare?

The MCP code-search ecosystem grew rapidly in late 2025 / early 2026 and many projects share the same baseline stack (Rust + tree-sitter + BM25 + embeddings + MCP). codesearch's deliberate focus is:

| Focus area | codesearch | Typical alternative | |---|---|---| | Repository scope | Multi-repo serve with cross-repo RRF | Usually single repo at a time | | Footprint | ~hundreds of MB, CPU-only, no Docker | GB-scale, GPU, Docker, or cloud | | Enterprise / offline | No runtime fetches; static binary | Often pulls models at first run | | Symbol navigation | find (def/usages/imports/dependents) co-located with semantic search | Often a separate code-graph tool | | Token cost per call | compact=true by default; chunks fetched on demand | Frequently dumps full snippets |

Other projects in the same niche may go deeper on call-graph traversal, polished standalone CLIs, or memory/knowledge-graph features. codesearch is intentionally narrower — it picks "lightweight, multi-repo, MCP-native, fully offline" and stays on that lane.

Architecture

graph TB
    Agent[AI Agent / MCP Client] -->|MCP stdio or HTTP| Router{MCP Router}

    Router --> Search[search tool]
    Router --> Find[find tool]
    Router --> Explore[explore tool]
    Router --> GetChunk[get_chunk tool]
    Router --> FindImpact[find_impact tool]
    Router --> Status[status tool]

    Search -->|mode=semantic| Semantic[Vector ANN + BM25 + RRF Fusion]
    Search -->|mode=literal| Literal[Tantivy FTS / Regex]

    Find -->|definition/usages| SymbolIndex[Symbol Index]
    Find -->|imports/dependents| DepGraph[Dependency Graph]

    Explore -->|outline| TreeSitter[Tree-sitter AST]
    Explore -->|similar| Semantic

    Semantic --> Arroy[arroy ANN vectors]
    Semantic --> Tantivy[Tantivy BM25]
    Arroy --> LMDB[(LMDB)]
    Tantivy --> TantivyIdx[(Tantivy Index)]

    GetChunk --> LMDB

    FindImpact -->|C# symbols| CSharpHelper[scip-csharp helper]
    CSharpHelper -->|SCIP index| ScipLMDB[(LMDB scip_symbols)]

    subgraph "Serve Mode (multi-repo)"
        ServeRouter[HTTP Router] -->|project/group routing| Repo1[Repo A]
        ServeRouter --> Repo2[Repo B]
        ServeRouter --> RepoN[Repo N]
    end

    Router -->|client mode| ServeRouter

Quick Start

Install

Download pre-built binaries from Releases:

| Platform | Download | |----------|----------| | Windows x8664 | codesearch-windows-x86_64.zip | | Windows x8664 + C# | codesearch-windows-x86_64-with-csharp.zip | | Linux x8664 | codesearch-linux-x86_64.tar.gz | | Linux x8664 + C# | codesearch-linux-x86_64-with-csharp.tar.gz | | macOS ARM64 | codesearch-macos-arm64.tar.gz | | macOS ARM64 + C# | codesearch-macos-arm64-with-csharp.tar.gz |

Or build from source:

git clone https://github.com/flupkede/codesearch.git
cd codesearch
cargo build --release

Index a repository

# Register and index the current repo (adds to ~/.codesearch/repos.json)
codesearch index add

# Register and index a repo from outside the repo folder
codesearch index add /path/to/my-project

# Incremental update (only changed files)
codesearch index /path/to/my-project

# Full rebuild
codesearch index /path/to/my-project --force

# Remove a repo
codesearch index rm /path/to/my-project

# List registered repos
codesearch index list

# Remove stale entries (relocates moved repos first, then drops the rest)
codesearch index prune

codesearch index add is intended to be run from inside the repo you want to register. If you're launching it from somewhere else, pass the repo path explicitly.

First-time indexing takes 2–5 minutes. Subsequent runs are incremental (10–30s). Branch switches trigger automatic re-indexing.

MCP Configuration

codesearch connects to AI agents via MCP. Two modes:

| Mode | How | Best for | |------|-----|----------| | Local (stdio) | codesearch mcp — single repo, auto-index + file watching | Working on one project | | Serve (HTTP) | codesearch serve — multi-repo, TUI dashboard, lazy FSW | Multiple repos, cross-repo search |

Local / Single Repo

The agent spawns codesearch mcp as a subprocess. It auto-detects the nearest index and starts a file watcher.

OpenCode — ~/.config/opencode/config.json:

{
  "mcp": {
    "codesearch": {
      "type": "local",
      "command": ["codesearch", "mcp"],
      "enabled": true
    }
  }
}

Claude Code — ~/.config/claude-code/config.json:

{
  "mcpServers": {
    "codesearch": {
      "command": "codesearch",
      "args": ["mcp"]
    }
  }
}

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "codesearch": {
      "command": "codesearch",
      "args": ["mcp"]
    }
  }
}

Serve / Multi-Repo

Start the server first, then connect your agent. The server manages all registered repos with a TUI dashboard, lazy filesystem watchers, and idle eviction.

# Start the server (default port 39725)
codesearch serve

OpenCode — connect via HTTP:

{
  "mcp": {
    "codesearch": {
      "type": "remote",
      "url": "http://127.0.0.1:39725/mcp",
      "enabled": true
    }
  }
}

Claude Code / Claude Desktop — force serve connection via --mode client:

{
  "mcpServers": {
    "codesearch": {
      "command": "codesearch",
      "args": ["mcp", "--mode", "client"]
    }
  }
}

> Note: In multi-repo mode, agents must specify project or group in tool calls. status always works without scope. get_chunk auto-routes when the chunk_id is unique across repos; if ambiguous, it returns candidates and requires project.

Agent Guidance (making agents use codesearch, not grep)

codesearch publishes instructions to every MCP client on connect (via the initialize handshake). These tell the agent when to reach for codesearch vs grep/glob, which tool to pick, and the service-mode caveats (paths are from the server's filesystem; not every directory is indexed). Most clients (OpenCode, Cursor) surface these automatically.

If your agent skips codesearch and falls back to grep/glob too often, add this quickstart to its project rules (AGENTS.md for Claude Code / OpenCode, .cursorrules for Cursor, custom instructions for others):

## Codesearch quickstart

Prefer codesearch over manual grep/glob for:
- semantic, cross-file, or symbol-oriented lookup
- cases where you don't know the exact file path
- "where is X implemented", "find usages of Y", "how does Z flow through the code"

Use plain grep/glob instead for:
- a single known file
- trivial one-line edits
- exact literal searches

When codesearch runs as a remote service (`codesearch serve` on another host),
the paths it returns are from the SERVER's filesystem. Use the `get_chunk` tool
to read content — don't try to open returned paths locally. Not every directory
is indexed (e.g. `.venv`, `node_modules`, `build/`); if a search returns nothing,
the dir may simply be unindexed.

> OpenCode users: the user-level ~/.config/opencode/AGENTS.md is the right place for this — it applies across all projects. Claude Code reads a project-level AGENTS.md instead, so add the quickstart per-project (or symlink a shared one).

MCP Tools Reference

search — Code Search

| Parameter | Type | Description | |-----------|------|-------------| | query | string | Natural language, code snippet, regex, or exact term | | mode | "semantic" \| "literal" | Search backend (default: semantic) | | filter_path | string | Path prefix filter (semantic mode) | | file_glob | string | Glob filter (literal mode), e.g. "src/**/*.rs" | | language | string | Language filter (literal mode) | | regex | bool | Treat query as regex (literal mode) | | phrase | bool | Exact phrase match (literal mode) | | compact | bool | Metadata only, no code (default: true) | | limit | int | Max results (default: 10 semantic, 20 literal) | | project | string | Target specific repo (multi-repo) | | group | string | Search across repo group (multi-repo) |

Semantic mode combines vector similarity (fastembed) + BM25 lexical scoring + exact identifier boosting, fused with RRF. Best for conceptual queries and mixed natural-language + symbol searches.

Literal mode uses Tantivy FTS. Use regex=true for patterns with punctuation (foo::bar, Vec). Use phrase=true for multi-word exact matches.

find — Symbol Navigation

| Parameter | Type | Description | |-----------|------|-------------| | symbol | string | Symbol name or file path (for imports) | | kind | "definition" \| "usages" \| "imports" \| "dependents" | Navigation type | | definition_kind | string | Filter: Function, Class, Method, Struct, Trait, Enum, Interface | | project / group | string | Multi-repo routing |

explore — File Exploration

| Parameter | Type | Description | |-----------|------|-------------| | target | string | File path (outline) or chunk_id (similar) | | kind | "outline" \| "similar" | Exploration type | | limit | int | Max results for similar mode | | project / group | string | Multi-repo routing |

Outline returns all top-level symbols in a file (kind, signature, line range). Similar finds semantically related chunks to a given chunk_id.

get_chunk — Read Code

| Parameter | Type | Description | |-----------|------|-------------| | chunk_id | int | Chunk ID from search/explore results | | context_lines | int | Extra lines before/after (0-20, default: 0) | | project | string | Disambiguate if chunk_id exists in multiple repos |

In multi-repo mode: auto-routes when chunk_id is unique; returns candidates list when ambiguous.

find_impact — Symbol Reference Impact

Find all call-sites and references to a symbol with file/line precision, powered by per-language semantic analysis. Currently supports C# (via the bundled scip-csharp helper).

| Parameter | Type | Description | |-----------|------|-------------| | symbol_name | string | Symbol name (e.g. "FieldDefinition.Validate") | | file | string | File path for position-based lookup | | line | int | Line number for position-based lookup | | language | string | Language hint (auto-detected from file extension) | | project / group | string | Multi-repo routing |

Returns a list of references with file, start_line, end_line, and kind (e.g. "call", "definition"). Exposes index_age_seconds so agents can reason about staleness.

> Note: Requires the -with-csharp release variant or a separately installed scip-csharp helper. See [C# Semantic Search](#c-semantic-search).

status — Index Info

| Parameter | Type | Description | |-----------|------|-------------| | kind | "index" \| "projects" | What to query | | project / group | string | Multi-repo routing |

Serve Mode (Multi-Repo)

For working across multiple repositories simultaneously:

codesearch serve

This starts a background HTTP server with:

• TUI dashboard (ratatui) showing repo status, CPU usage, active sessions
• Lazy filesystem watchers — activated on first query per repo
• Idle eviction (30min) — unused repos are unloaded from memory
• Session tracking via MCP keep-alive

TUI Keyboard Shortcuts

| Key | Action | |-----|--------| | ↑ / ↓ | Navigate repo list | | i | Show info overlay (chunks, files, model, DB size) | | d | Run doctor diagnostics on selected repo | | f | Force reindex selected repo | | r | Remove selected repo (with confirmation dialog) | | s | Reload repos config from disk | | q | Quit serve |

Repository Registration

Repos are registered via codesearch index add:

# Register a repo (creates index + adds to ~/.codesearch/repos.json)
codesearch index add /path/to/my-project

# Remove a repo
codesearch index rm /path/to/my-project

# List registered repos
codesearch index list

# Clean up stale entries (relocates moved repos, drops the rest)
codesearch index prune

The repository alias (the key in repos.json, used for groups and the MCP project argument) is always derived automatically from the directory name — there is no --alias flag.

Serve reads ~/.codesearch/repos.json on startup and manages all registered repos.

Moved or renamed repositories

If you rename or move a registered folder, serve does not crash. On startup it tries to relocate each missing repo automatically: it captures every repo's git remote (remote.origin.url) at registration, and on a missing path it scans nearby folders (bounded depth, override with CODESEARCH_RELOCATE_MAX_DEPTH, default 3) for a git checkout with the same remote. A single unambiguous match is rewritten into repos.json; otherwise the entry is logged and skipped (never indexed against a dead path). Run codesearch index prune to relocate what can be relocated and drop the rest.

A hand-edited repos.json is also tolerated: empty entries, orphaned metadata, and group references to unknown repos are cleaned up on load rather than crashing.

Groups

Groups let you search across related repositories:

codesearch groups add my-group --aliases repo1 repo2 repo3
codesearch groups list

Then in MCP tools: group="my-group" fans out the query to all repos in the group.

The all group

The name all is a reserved virtual group that always resolves to every registered repository — no setup required:

group="all"   # fans out to all repos, equivalent to listing every alias

• It is not stored in repos.json and always reflects the current set of registered repos (register or remove a repo and all updates automatically).
• It appears in codesearch groups list (marked virtual) and in the scope_required error's available_groups, so agents discover it without extra setup.
• It is not the default — when no project/group is specified in multi-repo mode, codesearch still returns scope_required (safe-by-default). Use group="all" explicitly when you want to search everywhere.
• codesearch groups add all and codesearch groups remove all are rejected — the name is reserved.

Git Worktree Auto-Index

When using git worktree add to create parallel working directories, codesearch can auto-register new worktrees via a post-checkout git hook.

Setup (run insi

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: flupkede
• Source: flupkede/codesearch
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.