Vex代码搜索

bge-large-en-v1.5, mxbai-large. Changing it requires a reindex.

Installation

```bash

GPU doctor — is the compiled EP actually engaging on this machine? (v1.16.0)

vex gpu # probes the compiled-in EP with strict registration vex gpu cuda # narrow to one EP vex gpu --enable # persist working device to VEX_DEVICE

rebuild lands for the next query. Trades freshness for latency.

GPU device for semantic indexing (GPU-enabled builds only). "auto" uses the

compiled-in GPU EP when it initializes, else CPU; or "cpu"/"cuda"/"directml"/

Install vex

brew tap tenatarika/tap && brew install vex

Source build (if you prefer or are on an unsupported triple)

cargo build --release -p vex-mcp

Quick Start

```bash

Find all usages of a symbol (--strict drops string-literal / comment / wrong-scope noise)

vex usages "IndexReader" --strict

Usages (FST)

References stored in an FST (Finite State Transducer) — zero-copy lookup from mmap with prefix search support.

rg: 20 matches across imports, usage sites, comments, tests (2,045 chars)

$ rg -w "PreAggregatedConfig" . ./models.py:3602:class PreAggregatedConfig(models.Model): ./models.py:3610: pre_aggregated_config = PreAggregatedConfig.objects.get(...) ./serializers.py:48:from .models import PreAggregatedConfig ./tests.py:12: config = PreAggregatedConfig(...) ... (16 more lines)

Bundle: 4 round-trips → 1 envelope (v1.9, Phase 13.2)

vex bundle --mode symbol --symbol PaymentService # body + callers + callees + similar vex bundle --mode pr-impact --base origin/main # changed symbols + transitive callers + tests vex bundle --mode project --top-n 30 # top-N by reverse call-graph indegree

Configuration

Create a .vex.toml in your project root to customize vex behavior:

vex init  # generates .vex.toml with commented defaults

```toml

"text" (verbose multi-line), or "json" (envelope for MCP / tools).

Set globally across projects with the VEX_EMBEDDER env var (this file wins).

Overridden by the --vcs flag and the $VEX_VCS env var. See docs/VCS-BACKENDS.md.

Keeping config out of the repo

Don't want a .vex.toml inside the repository (can't .gitignore it, shared checkout, etc.)? vex never creates one on its own — only vex init writes it — and you have two ways to keep config external:

- --config <path> / $VEX_CONFIG — point vex at a config file anywhere on disk. It replaces the in-repo lookup entirely, so the repo stays clean:

  vex --config ~/vex/this-repo.toml search Foo
  export VEX_CONFIG=~/vex/this-repo.toml   # or set it once per shell
  

The index itself is never written into the repo — it lives in the cache dir (--cache-dir / $VEX_CACHE_DIR / platform cache), so a clean repo is just a matter of config placement.

Environment variables

JSON envelope (for MCP / tool integration; what `vex-mcp` parses)

vex search "Foo" --format json ```

Pin a different default in .vex.toml via format = "text" if you want the verbose multi-line view at the terminal.

JSON envelope (v1.11.0 — BREAKING for bare-array parsers)

Every --format json subcommand wraps its payload in the Phase 13 envelope. Single shape, easy to detect via protocol_version:

{
  "protocol_version": "v1",
  "capabilities": { /* see `vex capabilities` */ },
  "_meta": { "vex.dev/index_age_ms": 1200, "ttlMs": 30000, "cacheScope": "project" },
  "results": [ /* the actual data, shape depends on the subcommand */ ]
}

Pre-v1.11 only search and bundle returned this envelope; the other ~14 subcommands (show, usages, pattern, grep, implementations, callers, callees, paths, reachable, tests-for, check, similar, duplicates, diff, outline, index, update, status, eval) emitted bare arrays / objects. Migration: pre-1.11 jq '.[0].name' or data[0]['name'] now needs jq '.results[0].name' / data['results'][0]['name']. Detect the envelope via response.get('protocol_version') == 'v1' to support both shapes during a rollout window.

Add to Claude Code MCP config (~/.claude/claude_desktop_config.json)

{ "mcpServers": { "vex": { "command": "/path/to/vex-mcp", "env": { "VEX_ROOT": "/path/to/your/project", "VEX_DEVICE": "auto" } } } } ```

VEX_DEVICE (v1.16.0) picks the GPU execution provider when the binary was built with gpu-cuda / gpu-directml / gpu-coreml — relevant when an MCP-driven index / update call rebuilds semantic embeddings on a large repo (51× CUDA / 29× DirectML over CPU on MiniLM-L6). auto is safe on CPU-only builds (degrades silently). Run vex gpu once to confirm the EP actually engages.

MCP Tools (27): - search — 3-way hybrid (structural + BM25 + semantic); accepts filter / include / exclude / kind / context_path / no_bm25 / --why / metadata filters / diff-scope (since / since_branched / changed_only) - find_symbol — exact name lookup - find_similar — semantic search by free-form description - similar — nearest neighbors of an existing symbol (explain adds Jaccard + diff); diff-scope - duplicates — near-duplicate symbol pairs (explain shows what differs); diff-scope - show — extract symbol body fr

Find implementations of a trait/interface

vex implementations "Iterator"

Interface OR class with the same name

vex pattern 'interface $N || class $N' --lang typescript

Claude Code (CLI Integration)

The recommended way to integrate vex with Claude Code is via CLAUDE.md rules (see below). Vex runs as a CLI tool — Claude Code calls it directly via Bash, no MCP server needed.

Setup:

```bash

Integration

How It Compares

Note: vex search speed assumes a pre-built index. Ripgrep and ast-grep require no upfront indexing and work immediately on any directory. The tradeoff is amortized: if you search the same codebase many times (typical in agent workflows), the one-time indexing cost pays for itself.

Best for: fast symbol search in AI agent workflows where token efficiency matters. Not a replacement for LSP-based tools (no refactoring, no go-to-definition in dependencies).

Search: vex vs ast-index vs ripgrep

Medium project (ast-index repo, 31K lines Rust, avg 10 runs):

Key takeaway: vex search is constant ~4-5 ms (FST O(query_len)) regardless of project size — this is the win the slower index build pays for. The ripgrep comparison is not apples-to-apples: rg scans raw text with no index, so it scales with corpus size (single-digit ms on this 31K-line repo, 100 ms+ on large ones), while vex does a pre-built FST lookup. The durable advantage is amortized and qualitative: vex returns only symbol definitions (precise, token-efficient), while rg returns every text occurrence (noisy, expensive in LLM contexts).

HNSW vs Brute-Force (semantic vector search)

The latency figures below were measured on an earlier build and not re-run in the v1.25.1 pass — read them as the scaling shape (HNSW stays flat, brute-force grows linearly), not current absolutes.

Semantic search embeds the query via ONNX (~55ms) then searches stored vectors. HNSW (usearch) replaces brute-force O(N) scan with O(log N) approximate nearest neighbor search:

HNSW stays constant ~3ms regardless of index size. Brute-force grows linearly. Total semantic search latency is dominated by ONNX embedding (~55ms), so end-to-end speedup is modest for small codebases but critical at scale.

Troubleshooting