code-search-cli

Semantic code-search MCP installer, indexer, and token-savings dashboard for AI coding agents.

csearch installs a local MCP server that indexes your repositories and gives agents a semantic search tool before they read large files or run broad shell searches. It also installs IDE-specific guidance so supported agents prefer code-search during repository exploration.

Features

• Installs the bundled code-search MCP runtime under ~/.csearch/code-search.
• Bootstraps each repository with a local .claude/mcp-code-search index directory.
• Installs supported IDE adapters and agent guidance.
• Keeps indexes fresh with git hooks, Cursor edit hooks, and lazy freshness checks.
• Tracks global token savings in ~/.csearch/metrics.jsonl.
• Provides csearch gain / csearch savings with input tokens, output tokens, saved tokens, efficiency, client/IDE grouping, tool grouping, and query grouping.
• Includes repair, reset, project discovery, and full reindex commands.

Installation

Requires Node.js 18 or newer.

npm install -g @bturkis/code-search-cli

Or run directly:

npx @bturkis/code-search-cli help

Quick Start

csearch install
csearch uninstall --yes
csearch status
csearch gain

csearch install detects installed IDEs, asks which supported adapters to configure, checks the OS package manager preflight, detects embedding runners, asks which runner/model to use, installs or pulls what is missing, writes the embedding config, installs agent guidance, bootstraps the current repository, and runs an incremental index.

For non-interactive installs:

csearch install --all
csearch install --ide cursor
csearch install --ide claude-code
csearch uninstall --all --yes

Supported IDE Adapters

Check detected IDEs:

csearch ides

Currently supported install targets:

• Cursor
• Claude Code

Detected but not yet supported targets are listed as unsupported and are not modified.

Agent guidance is installed as managed blocks/files:

• Cursor: ~/.cursor/rules/csearch-code-search.mdc
• Claude Code: ~/.claude/CLAUDE.md

Existing files are not overwritten. csearch only creates or updates the managed block between:

<!-- csearch managed guidance start -->
<!-- csearch managed guidance end -->

Package Manager Preflight

Runner installation requires an OS package manager. Check it with:

csearch doctor package-manager

If no supported package manager is available, install stops and prints the official setup link:

• macOS: Homebrew, https://brew.sh/
• Windows: Windows Package Manager, https://learn.microsoft.com/windows/package-manager/winget/
• Linux: apt, dnf, pacman, or zypper

Embedding Runner And Model Selection

install includes a runner/model wizard.

Supported runner targets:

• Ollama
• LM Studio

The installer first detects what is already installed and running. Installed runners are offered as-is. Missing supported runners are offered as install options when a supported OS package manager is available.

Recommended model options include:

• Ollama: nomic-embed-text (recommended, 768 dims)
• Ollama: mxbai-embed-large (1024 dims)
• LM Studio: text-embedding-nomic-embed-text-v1.5 (recommended, 768 dims)

For Ollama, missing models are pulled automatically with ollama pull <model>.

The selected embedding config is written to:

~/.csearch/code-search/config.json

You can change it later:

csearch config show
csearch config set-local
csearch config set-remote --url http://127.0.0.1:1234 --model text-embedding-nomic-embed-text-v1.5 --dims 768 --max-input-tokens 2048

No machine-specific LAN/Tailscale IP addresses are shipped in the default config. Remote endpoints are only written when selected during install or set explicitly with config set-remote. During indexing, csearch reads the loaded model's context metadata from the runner when available and splits chunks before sending them to LM Studio/Ollama. Because LM Studio/GGUF tokenizers can count code differently than csearch's estimator, csearch uses a conservative safety ratio for the actual chunk budget. Use --max-input-tokens only when the runner does not expose context metadata; Nomic v1/v1.5 falls back to a 2048-token context and indexes with a safer effective budget.

Commands

Install or Repair

csearch install
csearch install --all
csearch install --ide cursor
csearch fix --all

install and fix sync the MCP runtime, configure the selected embedding runner/model, repair IDE integrations, install agent guidance, repair repo-local bootstrap files, repair git hooks, and run an incremental index.

Install prints progress for each step, including package-manager checks, runner/model setup, runtime sync, IDE configuration, repository bootstrap, and index refresh.

Uninstall

csearch uninstall --yes
csearch uninstall --all --yes

uninstall removes the global runtime, global metrics, IDE MCP integrations, agent guidance, managed git hook blocks, repo-local .claude/mcp-code-search index artifacts, and generated repo .mcp.json code-search entries.

By default it cleans the current repository plus global runtime/IDE state. Use --all to also clean discovered repositories.

Status

csearch status
csearch doctor
csearch projects

status and doctor report the current repository's code-search MCP registration, edit hook, and index metadata.

projects lists discovered repo-local .claude/mcp-code-search indexes. Pass a scan root to narrow discovery, or set CODE_SEARCH_PROJECT_ROOTS to a path-delimited root list.

Token Savings

csearch gain
csearch savings
csearch gain --repo

By default, gain and savings read global stats from ~/.csearch/metrics.jsonl.

Metrics are recorded inside the MCP server before responses are returned to the IDE agent. Events are written for search_code, get_file, and list_exports, and include the MCP client name when the IDE provides it.

Example output:

Code-Search Token Savings (Global: 1/1 projects)
==============================================================================

Total searches:      1
Tokenizer:           js-tiktoken/cl100k_base
Input tokens:        8.3K
Output tokens:       1.8K
Tokens saved:        6.5K (78.4%)
Efficiency meter:    ███████████████████████████░░░░░░░  78.4%

Use --repo to filter the report to the current repository. Legacy repo-local metrics are still read for repo-scoped reports.

Reset Metrics

csearch reset
csearch reset --global --yes
csearch metrics reset

reset clears efficiency/gain statistics only: search counts, input tokens, output tokens, and saved token totals. Index artifacts are preserved.

Reindex

csearch reindex
csearch reindex --dry-run

reindex removes the current repository's index-meta.json and index-vectors.bin, then runs a full rebuild. Metrics are preserved.

Runtime Layout

Global runtime and stats:

~/.csearch/
  code-search/
  metrics.jsonl

Per-repository index:

<repo>/.claude/mcp-code-search/
  index-meta.json
  index-vectors.bin
  server.mjs
  config.json

Troubleshooting

• Run csearch fix --all if an IDE is not seeing the MCP server.
• Start a new IDE agent session after changing MCP config; long-lived MCP processes can keep old runtime state.
• Run csearch reindex if file counts or chunk counts look stale.
• Run csearch doctor package-manager before runner/model installation work.
• On Windows, if winget reports an MS Store source error while installing Ollama, run winget source update --name winget, then rerun csearch install. The installer pins runner installs to --source winget.
• On Windows, after a fresh Ollama install, the current terminal may not have the updated PATH yet. csearch checks common Ollama install paths, but if model pull still cannot find Ollama, open a new terminal and rerun csearch install.

Development

npm install
npm test
npm run check