AI 에이전트가 여러 인덱싱된 저장소를 대상으로 심층적인 의미론적 및 어휘적 코드 검색을 수행할 수 있도록 지원하며, 심볼 탐색과 AST 기반 청크 기능을 제공합니다.
다른 이름 flupkede/codesearch
- 스타
- 104
- Tools
- 20
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 11월 14일
- 라이선스
- Apache-2.0
codesearch MCP란?
codesearch은(는) MCP server입니다. AI 에이전트가 여러 인덱싱된 저장소를 대상으로 심층적인 의미론적 및 어휘적 코드 검색을 수행할 수 있도록 지원하며, 심볼 탐색과 AST 기반 청크 기능을 제공합니다. 20개 도구를 제공합니다. 예: query, mode, filter_path.
프로젝트 README에서 생성된 요약
codesearch MCP server 정보
codesearch는 AI 에이전트가 의미론적 및 어휘적 방식을 사용하여 여러 코드베이스를 검색할 수 있게 해줍니다. Rust 기반의 이 MCP server는 벡터 임베딩과 BM25 전문 검색을 Reciprocal Rank Fusion으로 결합하여 하이브리드 검색을 수행합니다. Docker나 GPU 없이 로컬 CPU에서 실행되도록 설계되어, 오프라인 상태를 유지해야 하는 기업 환경에 적합합니다.
사용자는 두 가지 방식으로 서버를 운영할 수 있습니다. stdio를 통해 단일 저장소를 작업하는 로컬 모드와, HTTP를 통해 여러 저장소를 오케스트레이션하는 서버 모드입니다. 이 서버는 search, find, explore, get_chunk, find_impact를 포함한 5가지 통합 도구를 제공합니다. 또한 17개 언어에 대해 tree-sitter를 사용한 AST 인식 청킹을 지원하여, 코드 스니펫이 임의의 줄이 아닌 함수나 클래스 단위로 정렬되도록 보장합니다. 이러한 접근 방식은 에이전트가 서로 다른 프로젝트 간의 심볼을 탐색하고, import를 추적하며, 정의를 효율적으로 찾는 데 도움을 줍니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
codesearch MCP 도구 20
README에서 감지됨querymodefilter_pathfile_globlanguageregexphrasecompactlimitprojectgroupsymbol
| query | — | |
| mode | — | |
| filter_path | — | |
| file_glob | — | |
| language | — | |
| regex | — | |
| phrase | — | |
| compact | — | |
| limit | — | |
| project | — | |
| group | — | |
| symbol | — |
도구 20개 모두 보기도구 수 줄이기
kinddefinition_kindtargetchunk_idcontext_linessymbol_namefileline
| kind | — | |
| definition_kind | — | |
| target | — | |
| chunk_id | — | |
| context_lines | — | |
| symbol_name | — | |
| file | — | |
| line | — |
자동 검사
2026년 11월 13일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능통과
- 오픈 소스 라이선스 (OSI)통과
- 최근 1년 내 커밋 또는 릴리스통과
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 원격 엔드포인트가 HTTPS 사용검사되지 않음
- 파괴적인 도구에 라벨 표시됨통과
- 모델에 대한 숨겨진 지침 없음통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
README
GitHub에서 보기codesearch
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 17 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 |
codesearch is intentionally narrower than full code-graph or knowledge-graph tools — 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 + federation)"
ServeRouter[HTTP Router] -->|project/group routing| Repo1[Repo A]
ServeRouter --> Repo2[Repo B]
ServeRouter --> RepoN[Repo N]
ServeRouter -->|"@peer fan-out · TLS"| CloudPeer["Cloud serve peer<br/>results merged via RRF"]
end
Router -->|client mode| ServeRouter
Quick Start
Install
One line — the installer asks for an install path on first use and updates an existing install in place (stopping a running serve from that directory first):
Windows (PowerShell):
irm https://github.com/flupkede/codesearch/releases/latest/download/install.ps1 -OutFile install.ps1; .\install.ps1
Linux / macOS (bash):
curl -fsSLO https://github.com/flupkede/codesearch/releases/latest/download/install.sh && bash install.sh && rm install.sh
(The download-then-run form matters: piping straight into bash shares stdin with the script, which breaks the first-install path prompt.)
Downloads the -with-csharp build by default (codesearch + scip-csharp, self-contained); add -NoCSharp / --no-csharp for the base build. Archives carry a .sha256 sidecar and the installer verifies it when present. --destination <path> / -Destination <path> skips the prompt.
| Platform | Download |
|---|---|
| Windows x86_64 | codesearch-windows-x86_64.zip |
| Windows x86_64 + C# | codesearch-windows-x86_64-with-csharp.zip |
| Linux x86_64 | codesearch-linux-x86_64.tar.gz |
| Linux x86_64 + 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 |
Unzip, put codesearch(.exe) on your PATH; for the C# builds keep scip-csharp(.exe) next to it.
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
codesearch index add is intended to be run from inside the repo you want to register — pass the path explicitly if launched from elsewhere. First-time indexing takes 2–5 minutes; subsequent runs are incremental (10–30s) and branch switches re-index automatically. Use codesearch index list/rm/prune to manage registrations (see Serve Mode).
Embedding model
The default quantized MiniLM model favors startup speed and a small download. For multilingual text and notes, EmbeddingGemma 300M is available as a quantized ONNX model with retrieval-specific query and document prompts:
codesearch --model embeddinggemma-q4 index /path/to/notes --force
Changing models requires a full reindex because embedding dimensions and vector
spaces are model-specific. Keep the same model selected for later indexing runs.
Search rejects a --model value that differs from the indexed model and points
to the required --force rebuild instead of mixing incompatible vector spaces.
In serve mode the model is resolved per repository, from each index's own
metadata, not from a hub-wide setting: a hub may hold indexes built with
different models, and every query is embedded with the model of the repo it
targets (mixed-model groups are fine). codesearch serve --model <name> sets a
default for newly created indexes: a repo added without an explicit model
(e.g. codesearch index add with no --model, delegated to serve) is indexed
with it, and it is reported in GET /status as default_model. It never
overrides an index that already records its own model — to change an existing
repo's model, re-index that repo
(codesearch --model <name> index <path> --force) and restart serve. A repo
whose metadata.json records no model (a legacy index built before the
recording contract) is queried with the built-in 384-dim default rather than the
serve default, and the search response carries a warning naming the assumed model
and the re-index command.
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 / Claude Desktop — ~/.config/claude-code/config.json or claude_desktop_config.json (identical schema):
{
"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
projectorgroupin tool calls.statusalways works without scope.get_chunkauto-routes when the chunk_id is unique across repos; if ambiguous, it returns candidates and requiresproject.
Agent Guidance (making agents use codesearch, not grep)
codesearch publishes instructions to every MCP client on connect (via the initialize handshake) — when to reach for codesearch vs grep/glob, which tool to pick, and the serve-mode caveats. Most clients (OpenCode, Cursor) surface these automatically.
If your agent skips codesearch and falls back to grep/glob too often, paste this quickstart into its rules (AGENTS.md for Claude Code/OpenCode, .cursorrules for Cursor):
Prefer codesearch for semantic, cross-file, or symbol-oriented lookup ("where is X implemented", "find usages of Y", "how does Z flow"). Use plain grep/glob for a single known file, trivial one-line edits, or exact literal searches. In remote-serve mode, returned paths are from the server's filesystem — read content via
get_chunkrather than opening paths locally, and unindexed dirs (.venv,node_modules,build/) simply return nothing.
OpenCode: put this in the user-level ~/.config/opencode/AGENTS.md (applies across all projects), or install the OpenCode plugin, which injects this guidance with the resolved project scope automatically. Claude Code reads a project-level AGENTS.md, so add it per-project (or symlink a shared one).
Claude Code specifically tends to ignore this advice more than other clients — its MCP tool schemas are deferred (an extra ToolSearch call is needed before codesearch tools are even callable), while Grep/Glob are always fully loaded and zero-friction, and spawned subagents don't inherit AGENTS.md or the MCP initialize instructions at all.
To make the preference structural instead of advisory, this repo ships five Claude Code hooks (four PreToolUse guards plus one PostToolUse companion):
grep-guard— onGrep. Blocks a grep against an in-repo path when codesearch covers that repo (the target repo — resolved from the grep target's own git root — is registered with the serve hub in~/.codesearch/repos.json, or aCODESEARCH_SERVERenv var is set for remote-serve setups), with a message telling the model how to load and call codesearch instead. Grep is auto-allowed only when the serve hub is genuinely down, established by a live probe of the unauthenticated/healthzendpoint (CODESEARCH_SERVER>127.0.0.1:$CODESEARCH_SERVE_PORT>127.0.0.1:39725); only a connection-level failure counts as down. A low-confidence or empty codesearch result is a successful call meaning "reformulate the query", so it does not open the escape hatch — the deny message steers tofind/explore/a single clean term instead. Greps outside any registered repo are never blocked, and the hook fails open (never traps the model).edit-guard— onEdit/Write/MultiEdit. Blocks an edit to a file in a codesearch-registered repo until codesearch was consulted for that exact path within the last 5 minutes —find_impactfor SCIP-backed languages (.cs .ts .tsx .mts .cts),find(kind="usages")for everything else — making the caller-aware-editing protocol structural. Its companionedit-guard-post(PostToolUse) records the markers on everyfind_impactcall and everyfind(kind="usages"); any outcome counts ("no results" included), so the guard can never wedge. Unregistered repos, non-git paths and hook failures fail open.subagent-preamble— onAgent(the subagent-spawn tool). Prepends a short codesearch preamble to every subagent prompt, since subagents otherwise don't inheritAGENTS.mdor MCP instructions at all — including the edit-guard protocol above.web-guard— onWebSearch/WebFetch. When you have remote documentation projects mounted (codesearch remote mount, e.g.cloud/inriver,cloud/example-dam), it blocks the first web call with guidance to search those indexed mounts first — often more precise and current than the open web. Same 5-minute retry-escape; when no mounts are configured it does nothing.
Install (idempotent — user scope applies to every project; --project is this repo only):
codesearch hooks claude install # preferred — self-contained, all platforms
codesearch hooks claude install --project # project scope (./.claude)
The native command embeds the hook scripts in the binary (no source tree needed) and merges the registrations into settings.json. The equivalent from-source installers still live in integrations/claude-code/ (install.ps1 / install.sh) if you'd rather run them directly.
OpenCode gets the same structural treatment through the OpenCode v2 plugin in integrations/opencode/: it resolves the session directory to an indexed project, injects scope-aware guidance once per session, rescues empty greps with index hits, optionally prunes or blocks grep/glob, keeps the serve hub healthy (with optional auto-start), and adds /codesearch* commands, a codesearch_scope tool, a skill and compaction assistance. Install by copying codesearch.ts into ~/.config/opencode/plugins/ — see the integration README.
Note: the grep-guard detects "codesearch is available for this repo" via that repo's registration with the serve hub (~/.codesearch/repos.json, honoring the CODESEARCH_REPOS_CONFIG / CODESEARCH_HOME overrides) or CODESEARCH_SERVER — not by checking whether a codesearch process is running (that runs almost constantly as a multi-repo hub and would false-fire in every directory), and not via a local .codesearch.db directory (a stale db from a since-unregistered repo used to deny Grep even though the hub could not answer for it). For a remote-serve setup with no local registration, set CODESEARCH_SERVER to opt back into enforcement.
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) |
filter_pathsemantics by routing mode:
- Local project (stdio, or
project=<local-alias>/local group on aservehub):filter_pathis a repo-relative prefix (e.g.src,docs/api) — matched against the routed project's own root, not the<alias>/…prefix shown in results.- Federated / mounted project (
project=<peer>/<alias>or an@peergroup fan-out):filter_pathis matched client-side on the namespaced result path (<peer>/<alias>/…) — i.e. exactly the path you see in the results — because the peer only matches its own un-namespaced store paths. The hub over-fetches from the peer and post-filters.Both modes now work without any client-side workaround; earlier releases dropped every hit when
filter_pathwas combined with a serve-routed or federated project.
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<T>). 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 — the recommended tool for "who calls X?" / "what breaks if I rename X?". Powered by per-language SCIP semantic analysis; precision backends ship per language: C# (bundled scip-csharp helper) and TypeScript (via npx scip-typescript, resolved on the host on demand — no bundle shipped), more planned. When no backend is available for a language, find_impact reports it — fall back to find kind="usages" (lexical) only then.
| 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: SCIP precision requires the
-with-csharprelease variant (or a separately installedscip-csharphelper) for C#, andnpx(withscip-typescript, fetched on first use) on the host's PATH for TypeScript. Without a backend for a language,find_impactreturns a clear message — usefind kind="usages"as the lexical fallback. See C# Semantic Search.
On a running codesearch serve the same lookup is available over plain REST — POST /find-impact with the identical request body, no MCP session required (same auth class as the other read-only REST endpoints).
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 |
n |
Force reindex selected repo |
r |
Remove selected repo (with confirmation dialog) |
l |
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;
# serve also does this itself at startup and on every status refresh)
codesearch index prune
Serve reads ~/.codesearch/repos.json on startup and manages all registered repos.
Moved, renamed or deleted 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).
When a path is unrecoverable, serve now unregisters it by itself — at
startup, and again on every background status refresh — so a deleted repo or
worktree stops showing up as a not indexed ghost on its own (worktree deletion
fires no git hook, and rm -rf bypasses every observer, so serve reconciles
its own registry instead). codesearch index prune stays available as the
manual trigger for the same sweep, e.g. while serve is not running.
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.
codesearch MCP 질문
codesearch MCP는 어떤 도구를 제공하나요?
20개 도구를 제공합니다. 예: query, mode, filter_path, file_glob, language.
codesearch를 실행하려면 GPU나 Docker가 필요한가요?
아니요. Docker 없이 CPU만으로 실행 가능하며, 수백 MB 정도의 가벼운 점유율을 가집니다.
어떤 MCP 클라이언트에서 codesearch를 사용할 수 있나요?
OpenCode, Claude Code, Cursor 및 모든 MCP 클라이언트에서 stdio 또는 HTTP를 통해 사용할 수 있습니다.
인덱싱 후에 임베딩 모델을 변경할 수 있나요?
네, 가능합니다. 다만 임베딩 차원과 벡터 공간은 모델마다 다르므로 전체 재인덱싱이 필요합니다.