Skip to content
Back to search

codesearch

Multi-repo semantic code search MCP server in Rust — hybrid vector + BM25 retrieval, tree-sitter AST chunking, fully offline. For OpenCode, Claude Code, Cursor, and any MCP client.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/flupkede/codesearch with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/flupkede/codesearch'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/flupkede--codesearch/badge.svg)](/listings/flupkede--codesearch)

HTML

<a href="/listings/flupkede--codesearch"><img src="/api/listings/flupkede--codesearch/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install

Download pre-built binaries from [Releases](https://github.com/flupkede/codesearch/releases):

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

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](#serve-mode-multi-repo)).

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 866 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # codesearch
  2. [![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
  3. [![Built with Rust](https://img.shields.io/badge/built%20with-Rust-orange.svg)](https://www.rust-lang.org/)
  4. [![MCP server](https://img.shields.io/badge/MCP-server-8a2be2.svg)](https://modelcontextprotocol.io/)
  5. [![GitHub release](https://img.shields.io/github/v/release/flupkede/codesearch?include_prereleases)](https://github.com/flupkede/codesearch/releases)
  6. [![GitHub stars](https://img.shields.io/github/stars/flupkede/codesearch?style=social)](https://github.com/flupkede/codesearch/stargazers)
  7. **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.**
  8. 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.
  9. ## Why codesearch?
  10. - **Multi-repo serve mode**: Fan-out queries across repository groups with cross-repo RRF ranking
  11. - **Hybrid retrieval**: Vector embeddings + BM25 full-text search fused with Reciprocal Rank Fusion
  12. - **Symbol navigation**: Jump to definitions, find usages, trace imports and dependents — in the same tool
  13. - **AST-aware chunking**: Tree-sitter parsing for 17 languages — chunks align to functions/classes (and Markdown sections), not arbitrary line ranges
  14. - **Token-efficient**: Returns metadata by default; agents fetch full code only when needed via `get_chunk`
  15. - **Lightweight footprint**: Hundreds of MB on disk, runs on CPU only, no runtime model downloads (works behind enterprise proxies)
  16. - **Zero config for single repos**: `codesearch index && codesearch mcp` — done
  17. ## How does this compare?
  18. 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:
  19. | Focus area | codesearch | Typical alternative |
  20. |---|---|---|
  21. | Repository scope | Multi-repo serve with cross-repo RRF | Usually single repo at a time |
  22. | Footprint | ~hundreds of MB, CPU-only, no Docker | GB-scale, GPU, Docker, or cloud |
  23. | Enterprise / offline | No runtime fetches; static binary | Often pulls models at first run |
  24. | Symbol navigation | `find` (def/usages/imports/dependents) co-located with semantic search | Often a separate code-graph tool |
  25. | Token cost per call | `compact=true` by default; chunks fetched on demand | Frequently dumps full snippets |
  26. 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.
  27. ## Architecture
  28. ```mermaid
  29. graph TB
  30. Agent[AI Agent / MCP Client] -->|MCP stdio or HTTP| Router{MCP Router}
  31. Router --> Search[search tool]
  32. Router --> Find[find tool]
  33. Router --> Explore[explore tool]
  34. Router --> GetChunk[get_chunk tool]
  35. Router --> FindImpact[find_impact tool]
  36. Router --> Status[status tool]
  37. Search -->|mode=semantic| Semantic[Vector ANN + BM25 + RRF Fusion]
  38. Search -->|mode=literal| Literal[Tantivy FTS / Regex]
  39. Find -->|definition/usages| SymbolIndex[Symbol Index]
  40. Find -->|imports/dependents| DepGraph[Dependency Graph]
  41. Explore -->|outline| TreeSitter[Tree-sitter AST]
  42. Explore -->|similar| Semantic
  43. Semantic --> Arroy[arroy ANN vectors]
  44. Semantic --> Tantivy[Tantivy BM25]
  45. Arroy --> LMDB[(LMDB)]
  46. Tantivy --> TantivyIdx[(Tantivy Index)]
  47. GetChunk --> LMDB
  48. FindImpact -->|C# symbols| CSharpHelper[scip-csharp helper]
  49. CSharpHelper -->|SCIP index| ScipLMDB[(LMDB scip_symbols)]
  50. subgraph "Serve Mode (multi-repo + federation)"
  51. ServeRouter[HTTP Router] -->|project/group routing| Repo1[Repo A]
  52. ServeRouter --> Repo2[Repo B]
  53. ServeRouter --> RepoN[Repo N]
  54. ServeRouter -->|"@peer fan-out · TLS"| CloudPeer["Cloud serve peer<br/>results merged via RRF"]
  55. end
  56. Router -->|client mode| ServeRouter
  57. ```
  58. ## Quick Start
  59. ### Install
  60. 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):
  61. **Windows (PowerShell):**
  62. ```powershell
  63. irm https://github.com/flupkede/codesearch/releases/latest/download/install.ps1 -OutFile install.ps1; .\install.ps1
  64. ```
  65. **Linux / macOS (bash):**
  66. ```bash
  67. curl -fsSLO https://github.com/flupkede/codesearch/releases/latest/download/install.sh && bash install.sh && rm install.sh
  68. ```
  69. (The download-then-run form matters: piping straight into `bash` shares stdin with the script, which breaks the first-install path prompt.)
  70. 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.
  71. <details>
  72. <summary>Manual install — download pre-built binaries from <a href="https://github.com/flupkede/codesearch/releases">Releases</a></summary>
  73. | Platform | Download |
  74. |----------|----------|
  75. | Windows x86_64 | `codesearch-windows-x86_64.zip` |
  76. | Windows x86_64 + C# | `codesearch-windows-x86_64-with-csharp.zip` |
  77. | Linux x86_64 | `codesearch-linux-x86_64.tar.gz` |
  78. | Linux x86_64 + C# | `codesearch-linux-x86_64-with-csharp.tar.gz` |
  79. | macOS ARM64 | `codesearch-macos-arm64.tar.gz` |
  80. | macOS ARM64 + C# | `codesearch-macos-arm64-with-csharp.tar.gz` |
  81. Unzip, put `codesearch(.exe)` on your `PATH`; for the C# builds keep `scip-csharp(.exe)` next to it.
  82. </details>
  83. Or build from source:
  84. ```bash
  85. git clone https://github.com/flupkede/codesearch.git
  86. cd codesearch
  87. cargo build --release
  88. ```
  89. ### Index a repository
  90. ```bash
  91. # Register and index the current repo (adds to ~/.codesearch/repos.json)
  92. codesearch index add
  93. # Register and index a repo from outside the repo folder
  94. codesearch index add /path/to/my-project
  95. # Incremental update (only changed files)
  96. codesearch index /path/to/my-project
  97. # Full rebuild
  98. codesearch index /path/to/my-project --force
  99. ```
  100. `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](#serve-mode-multi-repo)).
  101. ### Embedding model
  102. The default quantized MiniLM model favors startup speed and a small download. For
  103. multilingual text and notes, EmbeddingGemma 300M is available as a quantized ONNX
  104. model with retrieval-specific query and document prompts:
  105. ```bash
  106. codesearch --model embeddinggemma-q4 index /path/to/notes --force
  107. ```
  108. Changing models requires a full reindex because embedding dimensions and vector
  109. spaces are model-specific. Keep the same model selected for later indexing runs.
  110. Search rejects a `--model` value that differs from the indexed model and points
  111. to the required `--force` rebuild instead of mixing incompatible vector spaces.
  112. In **serve** mode the model is resolved **per repository**, from each index's own
  113. metadata, not from a hub-wide setting: a hub may hold indexes built with
  114. different models, and every query is embedded with the model of the repo it
  115. targets (mixed-model groups are fine). `codesearch serve --model <name>` sets a
  116. **default for newly created indexes**: a repo added without an explicit model
  117. (e.g. `codesearch index add` with no `--model`, delegated to serve) is indexed
  118. with it, and it is reported in `GET /status` as `default_model`. It never
  119. overrides an index that already records its own model — to change an existing
  120. repo's model, re-index that repo
  121. (`codesearch --model <name> index <path> --force`) and restart serve. A repo
  122. whose `metadata.json` records no model (a legacy index built before the
  123. recording contract) is queried with the built-in 384-dim default rather than the
  124. serve default, and the search response carries a warning naming the assumed model
  125. and the re-index command.
  126. ## MCP Configuration
  127. codesearch connects to AI agents via MCP. Two modes:
  128. | Mode | How | Best for |
  129. |------|-----|----------|
  130. | **Local (stdio)** | `codesearch mcp` — single repo, auto-index + file watching | Working on one project |
  131. | **Serve (HTTP)** | `codesearch serve` — multi-repo, TUI dashboard, lazy FSW | Multiple repos, cross-repo search |
  132. ### Local / Single Repo
  133. The agent spawns `codesearch mcp` as a subprocess. It auto-detects the nearest index and starts a file watcher.
  134. **OpenCode** — `~/.config/opencode/config.json`:
  135. ```json
  136. {
  137. "mcp": {
  138. "codesearch": {
  139. "type": "local",
  140. "command": ["codesearch", "mcp"],
  141. "enabled": true
  142. }
  143. }
  144. }
  145. ```
  146. **Claude Code / Claude Desktop** — `~/.config/claude-code/config.json` or `claude_desktop_config.json` (identical schema):
  147. ```json
  148. {
  149. "mcpServers": {
  150. "codesearch": {
  151. "command": "codesearch",
  152. "args": ["mcp"]
  153. }
  154. }
  155. }
  156. ```
  157. ### Serve / Multi-Repo
  158. Start the server first, then connect your agent. The server manages all registered repos with a TUI dashboard, lazy filesystem watchers, and idle eviction.
  159. ```bash
  160. # Start the server (default port 39725)
  161. codesearch serve
  162. ```
  163. **OpenCode** — connect via HTTP:
  164. ```json
  165. {
  166. "mcp": {
  167. "codesearch": {
  168. "type": "remote",
  169. "url": "http://127.0.0.1:39725/mcp",
  170. "enabled": true
  171. }
  172. }
  173. }
  174. ```
  175. **Claude Code / Claude Desktop** — force serve connection via `--mode client`:
  176. ```json
  177. {
  178. "mcpServers": {
  179. "codesearch": {
  180. "command": "codesearch",
  181. "args": ["mcp", "--mode", "client"]
  182. }
  183. }
  184. }
  185. ```
  186. > **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`.
  187. ### Agent Guidance (making agents use codesearch, not grep)
  188. 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.
  189. 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):
  190. > 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_chunk` rather than opening paths locally, and unindexed dirs (`.venv`, `node_modules`, `build/`) simply return nothing.
  191. OpenCode: put this in the user-level `~/.config/opencode/AGENTS.md` (applies across all projects), or install the [OpenCode plugin](integrations/opencode/README.md), 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).
  192. **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.
  193. To make the preference **structural** instead of advisory, this repo ships five Claude Code hooks (four `PreToolUse` guards plus one `PostToolUse` companion):
  194. - **`grep-guard`** — on `Grep`. 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 a `CODESEARCH_SERVER` env 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 `/healthz` endpoint (`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 to `find`/`explore`/a single clean term instead. Greps outside any registered repo are never blocked, and the hook fails open (never traps the model).
  195. - **`edit-guard`** — on `Edit`/`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_impact` for SCIP-backed languages (`.cs .ts .tsx .mts .cts`), `find(kind="usages")` for everything else — making the caller-aware-editing protocol structural. Its companion **`edit-guard-post`** (`PostToolUse`) records the markers on every `find_impact` call and every `find(kind="usages")`; any outcome counts ("no results" included), so the guard can never wedge. Unregistered repos, non-git paths and hook failures fail open.
  196. - **`subagent-preamble`** — on `Agent` (the subagent-spawn tool). Prepends a short codesearch preamble to every subagent prompt, since subagents otherwise don't inherit `AGENTS.md` or MCP instructions at all — including the edit-guard protocol above.
  197. - **`web-guard`** — on `WebSearch`/`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.
  198. Install (idempotent — user scope applies to every project; `--project` is this repo only):
  199. ```bash
  200. codesearch hooks claude install # preferred — self-contained, all platforms
  201. codesearch hooks claude install --project # project scope (./.claude)
  202. ```
  203. 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/`](integrations/claude-code/) (`install.ps1` / `install.sh`) if you'd rather run them directly.
  204. **OpenCode** gets the same structural treatment through the OpenCode v2 plugin in [`integrations/opencode/`](integrations/opencode/README.md): 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](integrations/opencode/README.md).
  205. 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.
  206. ## MCP Tools Reference
  207. ### `search` — Code Search
  208. | Parameter | Type | Description |
  209. |-----------|------|-------------|
  210. | `query` | string | Natural language, code snippet, regex, or exact term |
  211. | `mode` | `"semantic"` \| `"literal"` | Search backend (default: semantic) |
  212. | `filter_path` | string | Path prefix filter (semantic mode) |
  213. | `file_glob` | string | Glob filter (literal mode), e.g. `"src/**/*.rs"` |
  214. | `language` | string | Language filter (literal mode) |
  215. | `regex` | bool | Treat query as regex (literal mode) |
  216. | `phrase` | bool | Exact phrase match (literal mode) |
  217. | `compact` | bool | Metadata only, no code (default: true) |
  218. | `limit` | int | Max results (default: 10 semantic, 20 literal) |
  219. | `project` | string | Target specific repo (multi-repo) |
  220. | `group` | string | Search across repo group (multi-repo) |
  221. > **`filter_path` semantics by routing mode:**
  222. > - **Local** project (stdio, or `project=<local-alias>`/local group on a `serve` hub): `filter_path`
  223. > is a **repo-relative** prefix (e.g. `src`, `docs/api`) — matched against the routed project's own
  224. > root, not the `<alias>/…` prefix shown in results.
  225. > - **Federated / mounted** project (`project=<peer>/<alias>` or an `@peer` group fan-out): `filter_path`
  226. > is matched **client-side on the namespaced result path** (`<peer>/<alias>/…`) — i.e. exactly the
  227. > path you see in the results — because the peer only matches its own un-namespaced store paths. The
  228. > hub over-fetches from the peer and post-filters.
  229. >
  230. > Both modes now work without any client-side workaround; earlier releases dropped every hit when
  231. > `filter_path` was combined with a serve-routed or federated project.
  232. **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.
  233. **Literal mode** uses Tantivy FTS. Use `regex=true` for patterns with punctuation (`foo::bar`, `Vec<T>`). Use `phrase=true` for multi-word exact matches.
  234. ### `find` — Symbol Navigation
  235. | Parameter | Type | Description |
  236. |-----------|------|-------------|
  237. | `symbol` | string | Symbol name or file path (for imports) |
  238. | `kind` | `"definition"` \| `"usages"` \| `"imports"` \| `"dependents"` | Navigation type |
  239. | `definition_kind` | string | Filter: Function, Class, Method, Struct, Trait, Enum, Interface |
  240. | `project` / `group` | string | Multi-repo routing |
  241. ### `explore` — File Exploration
  242. | Parameter | Type | Description |
  243. |-----------|------|-------------|
  244. | `target` | string | File path (outline) or chunk_id (similar) |
  245. | `kind` | `"outline"` \| `"similar"` | Exploration type |
  246. | `limit` | int | Max results for similar mode |
  247. | `project` / `group` | string | Multi-repo routing |
  248. **Outline** returns all top-level symbols in a file (kind, signature, line range).
  249. **Similar** finds semantically related chunks to a given chunk_id.
  250. ### `get_chunk` — Read Code
  251. | Parameter | Type | Description |
  252. |-----------|------|-------------|
  253. | `chunk_id` | int | Chunk ID from search/explore results |
  254. | `context_lines` | int | Extra lines before/after (0-20, default: 0) |
  255. | `project` | string | Disambiguate if chunk_id exists in multiple repos |
  256. In multi-repo mode: auto-routes when chunk_id is unique; returns candidates list when ambiguous.
  257. ### `find_impact` — Symbol Reference Impact
  258. 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.
  259. | Parameter | Type | Description |
  260. |-----------|------|-------------|
  261. | `symbol_name` | string | Symbol name (e.g. `"FieldDefinition.Validate"`) |
  262. | `file` | string | File path for position-based lookup |
  263. | `line` | int | Line number for position-based lookup |
  264. | `language` | string | Language hint (auto-detected from file extension) |
  265. | `project` / `group` | string | Multi-repo routing |
  266. 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.
  267. > **Note:** SCIP precision requires the `-with-csharp` release variant (or a separately installed `scip-csharp` helper) for C#, and `npx` (with `scip-typescript`, fetched on first use) on the host's PATH for TypeScript. Without a backend for a language, `find_impact` returns a clear message — use `find kind="usages"` as the lexical fallback. See [C# Semantic Search](#c-semantic-search).
  268. 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).
  269. ### `status` — Index Info
  270. | Parameter | Type | Description |
  271. |-----------|------|-------------|
  272. | `kind` | `"index"` \| `"projects"` | What to query |
  273. | `project` / `group` | string | Multi-repo routing |
  274. ## Serve Mode (Multi-Repo)
  275. For working across multiple repositories simultaneously:
  276. ```bash
  277. codesearch serve
  278. ```
  279. This starts a background HTTP server with:
  280. - **TUI dashboard** (ratatui) showing repo status, CPU usage, active sessions
  281. - **Lazy filesystem watchers** — activated on first query per repo
  282. - **Idle eviction** (30min) — unused repos are unloaded from memory
  283. - **Session tracking** via MCP keep-alive
  284. ### TUI Keyboard Shortcuts
  285. | Key | Action |
  286. |-----|--------|
  287. | `↑` / `↓` | Navigate repo list |
  288. | `i` | Show info overlay (chunks, files, model, DB size) |
  289. | `d` | Run doctor diagnostics on selected repo |
  290. | `n` | Force reindex selected repo |
  291. | `r` | Remove selected repo (with confirmation dialog) |
  292. | `l` | Reload repos config from disk |
  293. | `q` | Quit serve |
  294. ### Repository Registration
  295. Repos are registered via `codesearch index add`:
  296. ```bash
  297. # Register a repo (creates index + adds to ~/.codesearch/repos.json)
  298. codesearch index add /path/to/my-project
  299. # Remove a repo
  300. codesearch index rm /path/to/my-project
  301. # List registered repos
  302. codesearch index list
  303. # Clean up stale entries (relocates moved repos, drops the rest;
  304. # serve also does this itself at startup and on every status refresh)
  305. codesearch index prune
  306. ```
  307. Serve reads `~/.codesearch/repos.json` on startup and manages all registered repos.
  308. #### Moved, renamed or deleted repositories
  309. If you rename or move a registered folder, serve does **not** crash. On startup
  310. it tries to **relocate** each missing repo automatically: it captures every
  311. repo's git remote (`remote.origin.url`) at registration, and on a missing path
  312. it scans nearby folders (bounded depth, override with
  313. `CODESEARCH_RELOCATE_MAX_DEPTH`, default `3`) for a git checkout with the same
  314. remote. A single unambiguous match is rewritten into `repos.json`; otherwise the
  315. entry is logged and skipped (never indexed against a dead path).
  316. When a path is unrecoverable, serve now **unregisters it by itself** — at
  317. startup, and again on every background status refresh — so a deleted repo or
  318. worktree stops showing up as a `not indexed` ghost on its own (worktree deletion
  319. fires no git hook, and `rm -rf` bypasses every observer, so serve reconciles
  320. its own registry instead). `codesearch index prune` stays available as the
  321. manual trigger for the same sweep, e.g. while serve is not running.
  322. A hand-edited `repos.json` is also tolerated: empty entries, orphaned metadata,
  323. and group references to unknown repos are cleaned up on load rather than
  324. crashing.
  325. ### Groups
  326. Groups let you search across related repositories:
  327. ```bash
  328. codesearch groups add my-group --aliases repo1 repo2 repo3
  329. codesearch groups list
  330. ```
  331. Then in MCP tools: `group="my-group"` fans out the query to all repos in the group.
  332. #### The `all` group
  333. The name `all` is a **reserved virtual group** that always resolves to *every* registered repository — no setup required:
  334. ```
  335. group="all" # fans out to all repos, equivalent to listing every alias
  336. ```
  337. - 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).
  338. - It appears in `codesearch groups list` (marked `virtual`) and in the `scope_required` error's `available_groups`, so agents discover it without extra setup.
  339. - 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.
  340. - `codesearch groups add all` and `codesearch groups remove all` are **rejected** — the name is reserved.
  341. ### Git Worktree Auto-Index
  342. When using `git worktree add` to create parallel working directories, codesearch can auto-register new worktrees via a `post-checkout` git hook.
  343. **Setup** (run inside any repo you want worktree auto-indexing for):
  344. ```bash
  345. codesearch hooks git install
  346. ```
  347. This installs a `post-checkout` hook that POSTs the worktree path to the running serve instance whenever a new worktree is checked out. The hook reads the serve URL from `~/.codesearch/serve_url` (`$CODESEARCH_HOME/serve_url` when the global root is relocated; automatically managed by `codesearch serve`).
  348. The install target is resolved with `git rev-parse --git-path hooks`, so it honours `core.hooksPath` (and, inside a linked worktree, the shared common-dir hooks) rather than assuming `.git/hooks/`. An existing `post-checkout` is not overwritten — codesearch's logic is chained in as a marker-delimited block.
  349. **How it works:**
  350. 1. `codesearch serve` writes its URL to `~/.codesearch/serve_url` (`$CODESEARCH_HOME/serve_url` when relocated) on startup (deletes on shutdown)
  351. 2. The `post-checkout` hook reads that file and POSTs the working directory to `POST /repos`
  352. 3. Serve registers the worktree path and begins indexing (deduped — won't re-register existing paths)
  353. ### Claude Code Guard Hooks
  354. `codesearch hooks claude install` (`--project` for repo scope) installs the four `PreToolUse` guard hooks that steer agents to codesearch before `Grep`/`WebSearch`/`WebFetch`/`Edit`/`Write`/`MultiEdit`, plus the `PostToolUse` marker hook (`edit-guard-post`) that records the consultations `edit-guard` requires. See [Agent Guidance](#agent-guidance-making-agents-use-codesearch-not-grep) above for what each guard does.
  355. ### MCP Connection Modes
  356. The `codesearch mcp` command supports three modes:
  357. | Mode | Behavior |
  358. |------|----------|
  359. | `auto` (default) | Connects to serve if running, otherwise local stdio |
  360. | `client` | Always connects to serve, fails if not running |
  361. | `local` | Always uses local DB (classic single-repo stdio) |
  362. ```bash
  363. codesearch mcp --mode client # force serve connection
  364. ```
  365. The serve endpoint is available at `/mcp` (Streamable HTTP transport).
  366. ### Federation (remote peers)
  367. codesearch can fan-out read queries (`search`, `get_chunk`) to **remote peers** — other `codesearch serve` instances (e.g. a cloud-hosted docs/KB peer) — and merge results with local indexes via RRF. This lets a team share one knowledge base while each dev keeps code search local.
  368. **Manage peer entries** (pure local config — does not call the remote):
  369. ```bash
  370. codesearch remote add cloud \
  371. --url https://codesearch-serve.<env>.<region>.azurecontainerapps.io \
  372. --api-key $API_KEY --timeout-secs 90
  373. codesearch remote list # show configured peers
  374. codesearch remote rm cloud # remove a peer entry
  375. ```
  376. A group then references a peer via `@`-prefix (`"groups": { "docs": ["@cloud"] }`), and `group="docs"` fans the query out over TLS. Remote misses never hard-fail — they degrade to local-only results with a `warnings` field.
  377. **Manage indexes ON a peer** — the same `index` verbs, scoped with `--remote <peer>`:
  378. ```bash
  379. # list the repos living on the cloud peer
  380. codesearch index list --remote cloud
  381. # register a path on the peer's filesystem (NOT your local FS)
  382. codesearch index add /data/docs/vendor-docs --remote cloud
  383. # remove a repo by its alias on the peer (NOT a local path)
  384. codesearch index rm inriver --remote cloud
  385. # trigger a background reindex of one repo on the peer
  386. codesearch index reindex inriver --remote cloud # incremental
  387. codesearch index reindex inriver --remote cloud --force # force full
  388. ```
  389. - `--remote` resolves `<peer>` against the peers you configured with `codesearch remote add`. An unknown peer produces a clear error listing the known ones.
  390. - With `--remote`, `add` takes a **path on the peer's filesystem** and `rm`/`reindex` take a **remote alias** (never your local path).
  391. - Without `--remote`, every `index` command behaves exactly as today (local).
  392. - `index list` and `index reindex` accept `--json` for agent-friendly output (**requires `--remote`**).
  393. - The write verbs (`add`, `reindex`, `--force`) require the peer to hold the repo **read-write**. A read-only / restore-only peer (e.g. a snapshot-restore cloud serve) rejects them — `--force` returns a clean HTTP 500 with a message, and `add` (a full embed) may OOM or time out a small replica. Use them against a writable peer; `list` is always safe.
  394. **Per-vendor layout on a peer.** Instead of registering one mixed corpus, register each vendor's sub-folder as its own repo so the peer's layout mirrors your local one. (Requires a **writable** peer — see the note above; a read-only restore-only peer rejects `add`.)
  395. ```bash
  396. for v in vendor-a-docs vendor-b-docs vendor-c-docs; do
  397. codesearch index add "/data/docs/$v" --remote cloud
  398. done
  399. codesearch index list --remote cloud # one alias per vendor
  400. ```
  401. **Mounting a peer's projects (opt-in, query one by name).** Adding a peer does **not** expose its projects automatically — you pick the individual indexes you want. Inspect what a peer offers, then mount the ones you care about:
  402. ```bash
  403. codesearch remote available cloud # list the peer's projects, ✓ marks mounted
  404. codesearch remote mount cloud/akeneo # opt in to a single index
  405. codesearch remote mounts # show what you've mounted
  406. codesearch remote unmount cloud/akeneo # opt back out
  407. ```
  408. A **mounted** project is addressable directly as `project=<peer>/<alias>` — a 1-to-1 passthrough to that peer's index:
  409. ```bash
  410. # search only the peer's akeneo docs, by name
  411. codesearch search "import products" --project cloud/akeneo
  412. ```
  413. The `remote_mounts` allowlist in `~/.codesearch/repos.json` is the single source of truth: a **non-mounted** project is unroutable (even if the peer exposes it), and a whole-peer `@peer` group reference (e.g. `docs → [@cloud]`) federates **only your mounted indexes** for that peer, not its whole corpus. Mounted projects are surfaced by `list_projects` (a `remote_projects` array) and advertised in the `scope_required` error, so agents can discover them.
  414. In the `codesearch serve` TUI, mounts appear in **italic/cyan**, distinguishing them from local indexes. Press `i` on a mount to see its **Remote Mount** info (peer URL + peer-reported status); the local-index actions (`doctor` / `reindex` / `remove`) are shown struck-through/disabled for a mount, since they act on a local index and a mount has none — manage a peer's indexes with `--remote` (above) instead.
  415. ## CLI Reference
  416. | Command | Description |
  417. |---------|-------------|
  418. | `codesearch index [PATH]` | Index a repo (incremental; `--force` for full rebuild) |
  419. | `codesearch search <QUERY>` | CLI search (for testing). `--literal` runs the FTS primitives directly (no embeddings/model load); `--phrase` for true adjacent multi-word phrases; `--regex` matches analyzed tokens only — a separator-spanning pattern with zero hits auto-falls back to a raw chunk-content scan |
  420. | `codesearch mcp` | Start MCP stdio server |
  421. | `codesearch serve` | Start multi-repo HTTP server with TUI |
  422. | `codesearch stats` | Show database statistics |
  423. | `codesearch clear` | Delete index |
  424. | `codesearch doctor` | Health check (model, index, config) |
  425. | `codesearch setup` | Download embedding models |
  426. | `codesearch cache stats\|clear` | Manage embedding cache |
  427. | `codesearch groups list\|add\|remove` | Manage repository groups |
  428. | `codesearch remote add\|list\|rm` | Manage federation peers (`--url`, `--api-key`, `--group`, `--into-group`, `--timeout-secs`) |
  429. | `codesearch remote available\|mount\|mounts\|unmount` | Inspect a peer's projects and opt-in mount them as `<peer>/<alias>` |
  430. | `codesearch index ... --remote <peer>` | Run `index list\|add\|rm\|reindex` against a peer's filesystem instead of local |
  431. | `codesearch hooks git install` | Install git post-checkout hook for worktree auto-indexing |
  432. | `codesearch hooks claude install` | Install Claude Code codesearch-first guard hooks into settings.json |
  433. ## Configuration
  434. ### Environment Variables
  435. | Variable | Description |
  436. |----------|-------------|
  437. | `CODESEARCH_SERVE_PORT` | Serve mode port (default: 39725) |
  438. | `CODESEARCH_SERVE_API_KEY` | API key for management endpoints + all endpoints when serve binds to a non-localhost address (unset = no auth) |
  439. | `CODESEARCH_ALLOWED_ROOTS` | Semicolon-separated allowed roots for repo registration (unset = all allowed) |
  440. | `CODESEARCH_ALLOWED_HOSTS` | Comma-separated hostname allowlist for the MCP streamable-HTTP transport (unset = loopback only: `localhost`, `127.0.0.1`, `::1`). Set this to your container/service hostname when serve runs behind a container network or reverse proxy — see [Security](#security). |
  441. | `CODESEARCH_DISABLE_HOST_VALIDATION` | `1`/`true` disables the MCP transport's Host-header allowlist entirely (DNS-rebinding protection off). Only safe behind a reverse proxy/firewall that already restricts inbound Host headers — see [Security](#security). |
  442. | `CODESEARCH_MCP_MODE` | MCP mode: auto, client, local |
  443. | `CODESEARCH_HOME` | Relocate the entire global root (`repos.json`, models cache, logs, `serve_url`, global ignore/extension files) away from `~/.codesearch`. Must be an absolute path; unset = `~/.codesearch`. Per-file overrides like `CODESEARCH_REPOS_CONFIG` still win |
  444. | `CODESEARCH_REPOS_CONFIG` | Path to repos.json |
  445. | `CODESEARCH_REPO_IDLE_TIMEOUT_SECS` | Idle eviction timeout (default: 1800) |
  446. | `CODESEARCH_STORE_LOCK_WAIT_SECS` | Bounded wait for a store's write lock before a single-project query reports the store busy (default: 300). Multi-repo fan-outs never wait — they skip the busy repo with a warning |
  447. | `CODESEARCH_MODEL_LOAD_TIMEOUT_SECS` | Bound on a cold-cache embedding-model load (default: 600). On expiry the loader fails fast with a hint to pre-populate the cache via `codesearch setup`; search itself only uses models already loaded or provably on disk |
  448. | `CODESEARCH_CACHE_MAX_MEMORY` | Embedding cache MB (default: 500) |
  449. | `CODESEARCH_MAX_LMDB_MAP_SIZE_MB` | Hard cap (MB) for LMDB auto-resize on `MDB_MAP_FULL`, applied to both the vector store and the persistent embedding cache (default: 16384 = 16GB; clamped to at least 1024). Raise this for very large corpora (millions of chunks) that legitimately exceed the default cap — see #189. |
  450. | `CODESEARCH_BATCH_SIZE` | Embedding batch size |
  451. | `CODESEARCH_INCREMENTAL_BATCH_SIZE` | Files read/chunked per incremental-refresh batch (default: 200) |
  452. | `CODESEARCH_INDEX_JOBS` | Max concurrent heavy repo jobs — refresh / reindex / HNSW build — in one serve process (default: 1; queries are never gated). See [Indexing limits](#indexing-limits) |
  453. | `CODESEARCH_EMBED_THREADS` | ONNX intra-op threads per embedding session (unset = ONNX default, all cores) |
  454. | `CODESEARCH_EMBED_PAUSE_MS` | Pause (ms) between background embedding mini-batches, a duty cycle for shared machines (default: 0) |
  455. | `CODESEARCH_MIN_FREE_MB` | Free-memory floor (MB) a heavy job waits for (max 30 s, then proceeds with a warning) before starting (default: 0 = disabled) |
  456. | `CODESEARCH_MAX_CHUNKS_PER_BATCH` | Hard cap on chunks held in memory per refresh batch; splits the batch early (default: 0 = disabled) |
  457. | `CODESEARCH_SCIP_CSHARP` | Override path to `scip-csharp` helper |
  458. | `CODESEARCH_EXTENSION_MAP` | Path to the extension→language map (default: `~/.codesearch/extensions.json`) — see [Extension map](#extension-map) |
  459. | `RUST_LOG` | Log level (e.g. `codesearch=debug`) |
  460. ### Indexing limits
  461. A serve hub with many repos used to start one full refresh/reindex/HNSW-build
  462. pass per repo as soon as that repo had work. A mass `git pull`, a burst of
  463. first queries, or several `POST /repos/:alias/reindex` calls therefore ran
  464. many CPU-heavy passes at once, held many file/chunk windows in memory, and
  465. queued the (already serialised) ONNX inference behind all of them. These knobs
  466. bound that work; they are read at startup, so a shell or systemd unit can set
  467. them without editing anything:
  468. | Knob | Default | Effect |
  469. |------|---------|--------|
  470. | `CODESEARCH_INDEX_JOBS` | `1` | Max repos doing a refresh / reindex / HNSW build at once. Queries never take this slot. |
  471. | `CODESEARCH_EMBED_THREADS` | unset (all cores) | ONNX intra-op threads per embedding session. |
  472. | `CODESEARCH_INCREMENTAL_BATCH_SIZE` | `200` | Files read/chunked per refresh batch. |
  473. | `CODESEARCH_MAX_CHUNKS_PER_BATCH` | `0` (off) | Split a batch early once it reaches this many chunks (a few huge files can produce more memory than many small ones). |
  474. | `CODESEARCH_EMBED_PAUSE_MS` | `0` | Sleep this long between background embedding mini-batches (duty cycle). |
  475. | `CODESEARCH_MIN_FREE_MB` | `0` (off) | A job waits (bounded to 30 s, then proceeds with a warning) until this much memory is free. |
  476. `codesearch serve` also accepts `--index-jobs`, `--embed-threads`,
  477. `--embed-pause-ms` and `--min-free-mb`, which set the corresponding variable
  478. for that process (flags win over the environment). Standalone `codesearch
  479. index` and `codesearch mcp` runs have no job gate and keep their previous
  480. behaviour; the embedding and batching variables still apply to them.
  481. Example for a large shared machine (128 cores, ~30 repos, dozens of repos
  482. indexed at once are the failure mode):
  483. ```ini
  484. # ~/.config/systemd/user/codesearch.service.d/limits.conf
  485. [Service]
  486. Environment=CODESEARCH_INDEX_JOBS=1
  487. Environment=CODESEARCH_EMBED_THREADS=8
  488. Environment=CODESEARCH_INCREMENTAL_BATCH_SIZE=100
  489. Environment=CODESEARCH_MAX_CHUNKS_PER_BATCH=5000
  490. Environment=CODESEARCH_EMBED_PAUSE_MS=25
  491. Environment=CODESEARCH_MIN_FREE_MB=4096
  492. # C# SCIP helpers are bounded separately; lower it for the same reason.
  493. Environment=CSHARP_SCIP_CONCURRENCY=1
  494. ```
  495. ### `.codesearchignore`
  496. Place in repo root. Gitignore syntax. Excludes paths from indexing:
  497. ```gitignore
  498. # Vendored code
  499. vendor/
  500. node_modules/
  501. # Generated files
  502. *.generated.cs
  503. **/migrations/**
  504. ```
  505. A **global** `.codesearchignore` can be placed at `~/.codesearch/.codesearchignore`. It applies to all repos with the lowest priority (repo-local `.codesearchignore`, `.gitignore`, and `.git/info/exclude` all override it). This is useful for patterns you want everywhere without modifying each repo.
  506. ### Extension map
  507. By default codesearch recognises the fixed extension list in [Supported
  508. Languages](#supported-languages); any other extension is `Unknown` and is
  509. **skipped entirely** (never indexed). To teach codesearch about a non-standard
  510. extension — or to deliberately remap a known one — drop a small JSON object at
  511. `~/.codesearch/extensions.json` mapping extension → language name:
  512. ```json
  513. {
  514. "inc": "php",
  515. "phtml": "php",
  516. "h": "cpp"
  517. }
  518. ```
  519. - Keys are file extensions, with or without a leading dot, case-insensitive
  520. (`"inc"`, `".inc"`, `".INC"` are equivalent). Only the **last** dot-suffix is
  521. matched, so `Foo.class.inc` maps via `"inc"`.
  522. - Values are language names — the names from the table above plus common aliases
  523. (`php`, `cpp`/`c++`, `csharp`/`c#`, `golang`, `js`, `ts`, …), case-insensitive.
  524. - The map applies to **all** indexed repos, and user entries **take precedence**
  525. over the built-ins (so `"h": "cpp"` overrides the default C mapping).
  526. - It's fully optional and fail-safe: a missing, empty, or malformed file simply
  527. means "no overrides" and is logged, never fatal. Unknown language names are
  528. skipped with a warning.
  529. - Set `CODESEARCH_EXTENSION_MAP` to load the file from a different path.
  530. > This is the supported answer to "my PHP is in `*.inc` files" (issue #138):
  531. > `.inc` is intentionally not a built-in because it's language-agnostic
  532. > (assembly, SQL, C/PHP includes all use it), so you opt in per your codebase.
  533. ### `repos.json`
  534. Located at `~/.codesearch/repos.json`. Managed by `codesearch index add/rm`. Contains repo aliases → paths and group definitions. See [Serve Mode](#serve-mode-multi-repo).
  535. ## Security
  536. This section documents the security model of **federation / remote peers** — the largest network surface in codesearch — followed by serve access control.
  537. ### Serve access control
  538. When `codesearch serve` is exposed beyond a single trusted user (shared dev machines, a network bind), two environment variables harden access:
  539. - **`CODESEARCH_SERVE_API_KEY`** — gates access depending on how serve is bound:
  540. - **Non-localhost bind** (`--host 0.0.0.0`, a LAN IP, etc.) — **ALL endpoints** require the key (health, status, MCP search, and management). Setting this variable is *required* when binding to a non-localhost address; serve refuses to start without it.
  541. - **Localhost bind** (default) — only **management endpoints** (`POST /repos`, `DELETE /repos/:alias`, `POST /repos/:alias/reindex`, `POST /reload`) require the key. Health, status, and MCP search remain open.
  542. - Send the key on every request via `Authorization: Bearer <key>` or `X-API-Key: <key>`.
  543. - **Client side:** `codesearch index add/rm/reindex` delegate to a running serve, so the CLI must send the same key. Set `CODESEARCH_SERVE_API_KEY` in the client's environment (same value as the server) and the CLI attaches it automatically. Without it, delegation returns `401` and falls back to local indexing — which risks LMDB file-lock conflicts if serve is still running.
  544. - **`CODESEARCH_ALLOWED_ROOTS`** — semicolon-separated list of filesystem roots. Repo registration is rejected for paths outside these roots. Prevents indexing arbitrary directories.
  545. Both are backward compatible: unset means no restriction (on a localhost bind).
  546. ### MCP transport host allowlist (DNS-rebinding protection)
  547. The MCP streamable-HTTP transport (via `rmcp`) validates the incoming `Host` header against an allowlist to defend against DNS-rebinding attacks. By default this allowlist is **loopback-only** (`localhost`, `127.0.0.1`, `::1`), which rejects requests carrying a container hostname or service-discovery name — a common trip-up in containerised/orchestrated deployments (Docker, Kubernetes, etc.) where the client connects via a non-loopback Host header.
  548. - **`CODESEARCH_ALLOWED_HOSTS`** — comma-separated list of extra allowed hostnames (e.g. `codesearch-serve,codesearch-serve.internal`), replacing the loopback-only default. Prefer this over disabling validation.
  549. - **`CODESEARCH_DISABLE_HOST_VALIDATION`** — set to `1` or `true` to disable Host-header validation entirely. This removes the DNS-rebinding protection outright; only use it when serve is already fenced off by a reverse proxy or network policy that restricts which Host headers can reach it.
  550. Precedence: disable > custom allowlist > default (loopback-only).
  551. ### Hardening against path traversal and injection
  552. Beyond the access-control gates above, codesearch applies several defense-in-depth mitigations at the filesystem and CLI boundary:
  553. - Project-path resolution (`index`, repo registration) fails fast on an unresolvable/malformed path instead of silently falling back to the raw, unvalidated input.
  554. - The `.NET` symbol-helper CLI (`scip-csharp`) canonicalizes every path argument (`--solution`, `--project`, `--output`, `--symbols-file`) before use.
  555. - Registering a project root that is itself a VCS/build-artifact directory (`.git`, `.svn`, `node_modules`, etc.) is rejected, preventing accidental indexing/exposure of internal VCS metadata.
  556. - Terminal output (search results, sync/reindex logs) strips ANSI/control-sequence injection from indexed file content before printing, so a maliciously crafted file can't manipulate the user's terminal.
  557. - On Unix, path-cache keys no longer collapse a literal backslash in a filename with a path separator (a Windows-only normalization rule is now gated to Windows).
  558. ### Operational note: file-descriptor limits under process supervisors
  559. `codesearch serve`'s file-descriptor demand scales with the number of registered repos (each warm repo holds LMDB + full-text-index + file-watcher handles). Under a process supervisor with a low default open-file limit (notably **macOS launchd**, default soft `ulimit -n 256`), a large repo count can silently exhaust file descriptors: `accept()` then fails with `EMFILE` and the daemon looks alive to its supervisor while refusing new connections. Serve now raises its own soft `RLIMIT_NOFILE` to the hard limit at startup (Unix only) and logs a warning if the effective limit still looks insufficient for the registered repo count — but if you see repeated `EMFILE`/"Too many open files" in the logs, raise the **hard** limit for the service (e.g. launchd `SoftResourceLimits`/`HardResourceLimits`, systemd `LimitNOFILE=`, or `ulimit -n` in the service's environment).
  560. ### Federation security model
  561. Federation is **operator-to-operator**, not end-user-facing. The only inputs that decide *where* requests go and *which key* they carry are the peer entries you register locally with `codesearch remote add` (stored in `~/.codesearch/repos.json`). No search query, MCP argument, or remote response ever becomes a request target or selects a key.
  562. - **Trust model.** Peers see your search queries (they must, to answer them) and return chunks. Register only peers whose operator you trust with that query visibility.
  563. - **No SSRF from queries.** Outbound calls go solely to URLs you configured; a search term cannot redirect the client to an attacker host.
  564. #### Secrets
  565. - **Storage.** Each peer's `api_key` is stored in **plaintext** in `~/.codesearch/repos.json` (your home directory, outside any git repo — it is never committed). Protect it with filesystem permissions, the same way you would an SSH key or a `.env` file. On the server side, inject the key from a secret store — the reference cloud deployment sets it as an Azure Container Apps secret (`secretref:api-key`), so it never sits in the image or in source.
  566. - **Transport.** The key is sent only as an `Authorization: Bearer <key>` header, over HTTPS. Use `https://` peer URLs; the federation client uses **rustls with certificate verification enabled** — there is no certificate-bypass (`danger_accept_invalid_certs`) anywhere in the codebase.
  567. - **Never in URLs or logs.** The key is not appended to query strings and is not written to logs; it lives only in the `Authorization` header of the in-flight request.
  568. #### Redirects
  569. The HTTP client follows up to 10 redirects by default (reqwest's standard policy) but **strips the `Authorization` header on cross-host redirects**. A peer that answers with a `3xx` to a different host therefore cannot exfiltrate the bearer token there; same-host redirects (e.g. path canonicalisation) preserve it. *Defense-in-depth:* if you suspect a peer's host or DNS has been compromised, rotate that peer's key.
  570. #### Serve-side enforcement
  571. The remote serve instance enforces its own auth on every inbound request from federation:
  572. - **Non-localhost bind** (any cloud/LAN deployment): **all** endpoints — including `/search` and `/chunk/:id` — require the key. The reference cloud peer binds `0.0.0.0`, so every federation fan-out carries the key and is rejected without it.
  573. - **Management endpoints** (`POST /repos`, `DELETE /repos/:alias`, `POST .../reindex`, `POST /reload`) require the key on every bind, localhost included.
  574. The `@peer` fan-out attaches the configured key via the same `bearer_auth` path the local CLI uses, so it satisfies both layers automatically.
  575. #### Write verbs (`index … --remote`)
  576. `add`, `rm`, and `reindex` against a peer are **authenticated management calls**. They carry the key like any other request and the *peer* decides whether to act (a read-only / restore-only peer rejects writes — see [Federation](#federation-remote-peers)). The local CLI only sends a path or alias for the peer to act on; it executes nothing on your machine and writes nothing to your filesystem.
  577. #### Cross-instance isolation
  578. On fan-out, the client strips the local `project` and forces `group` to the value configured for that peer (or `all`). Projects are local to each instance, so this prevents one instance's project names from leaking into another's query namespace.
  579. ## C# Semantic Search
  580. All C#-specific setup, operation, installation, and testing lives in [README_CSharp.md](README_CSharp.md).
  581. If you do not work with C# repos, you can skip it entirely.
  582. ## Supported Languages
  583. Tree-sitter AST-aware chunking:
  584. | Language | Extensions |
  585. |----------|-----------|
  586. | Rust | `.rs` |
  587. | Python | `.py`, `.pyw`, `.pyi` |
  588. | JavaScript | `.js`, `.mjs`, `.cjs` |
  589. | TypeScript | `.ts`, `.tsx`, `.jsx`, `.mts`, `.cts` |
  590. | C | `.c`, `.h` |
  591. | C++ | `.cpp`, `.cc`, `.cxx`, `.hpp`, `.hxx` |
  592. | C# | `.cs` |
  593. | Go | `.go` |
  594. | Java | `.java` |
  595. | Dart | `.dart` |
  596. | Shell | `.sh`, `.bash`, `.zsh` |
  597. | Ruby | `.rb`, `.rake` |
  598. | PHP | `.php` |
  599. | YAML | `.yaml`, `.yml` |
  600. | JSON | `.json` |
  601. | Markdown | `.md`, `.markdown`, `.txt` |
  602. | Jupyter | `.ipynb` |
  603. | Protobuf | `.proto` |
  604. Markdown uses the tree-sitter-md **block** grammar — chunks align to sections,
  605. headings, and code fences. Jupyter notebooks are parsed as JSON; code and
  606. markdown cells are extracted, tagged with `[code]` or `[markdown]`, and
  607. adjacent same-type cells under 50 lines are merged into single chunks.
  608. All other text files use line-based chunking as fallback.
  609. Files whose extension isn't recognised are treated as `Unknown` and **skipped
  610. entirely** (not indexed). If your codebase uses a non-standard extension for a
  611. supported language — e.g. legacy PHP in `*.inc` files, or `.h` you want parsed
  612. as C++ — map it explicitly with the [extension map](#extension-map).
  613. ## Core Technology
  614. | Component | Technology |
  615. |-----------|-----------|
  616. | Embedding | fastembed + ONNX Runtime (CPU) |
  617. | Vector store | arroy (Approximate Nearest Neighbors) + LMDB |
  618. | Full-text search | Tantivy (BM25, AND mode) |
  619. | Chunking | Tree-sitter AST parsing |
  620. | Incremental sync | SHA-256 content hashing |
  621. | Caching | 3-layer: in-memory (Moka) → persistent disk → query cache |
  622. | Schema | Versioned via `metadata.json` |
  623. ## Development
  624. ```bash
  625. # Build
  626. cargo build
  627. # Run tests
  628. cargo test
  629. # Check + lint
  630. cargo clippy --all-targets -- -D warnings
  631. # Format
  632. cargo fmt --all
  633. ```
  634. ## License
  635. Apache-2.0
  636. ## Acknowledgements
  637. This project is a fork of [demongrep](https://github.com/yxanul/demongrep) by [yxanul](https://github.com/yxanul). Huge thanks for building such a solid foundation.
  638. Built with: [fastembed-rs](https://github.com/Anush008/fastembed-rs), [arroy](https://github.com/meilisearch/arroy), [tantivy](https://github.com/quickwit-oss/tantivy), [tree-sitter](https://tree-sitter.github.io/), [ratatui](https://github.com/ratatui/ratatui), [LMDB](http://www.lmdb.tech/).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.