===============
LIBRARY RULES
===============
From library maintainers:
- Use `vex check <Name>` for exact-name lookup; it reports hit/miss with path:line and bypasses the ranker.
- Use `vex search "keywords"` only for fuzzy, multi-word exploration; when no symbol matches literally it returns ranked neighbors (callers, imports), not the definition.
- Use `vex show <Name>` to read a symbol's body instead of reading the whole file.
- Use `vex usages <Name> --strict` for refactors: binder-resolved references on Rust, TypeScript, Python, C#, C++, Go, Java and Kotlin; other languages fall back to a text scan.
- Use `vex grep <regex>` for text such as string literals, comments and config values, not for symbols.
- Exit code 1 means an empty result, not a failure; only exit code 2 is an error.
- Run `vex index` once per project and `vex update` afterwards; after an upgrade that bumps the index format, run `vex index` again.
- Pass `--format json` or `--format compact` for machine-readable, token-efficient output; connect agents with `vex mcp install --agent <name>`.

### Example .vex.toml GPU configuration

Source: https://github.com/tenatarika/vex/blob/main/docs/GPU_SUPPORT.md

Commented examples appended to DEFAULT_CONFIG in src/util/config.rs. Shows optional gpu and device keys; Option<T> deserializes to None when absent, so no backward-compat break.

```toml
# gpu = false        # use the GPU for embedding if this build supports it
# device = "auto"    # advanced: cpu | auto | cuda | directml | coreml

```

--------------------------------

### Install vex with Homebrew or from source

Source: https://github.com/tenatarika/vex/blob/main/README.md

Install vex via Homebrew on macOS/Linux or build from source using the Rust toolchain. The Homebrew commands set up the tap and install the binary; the source build clones the repository, compiles with cargo, and copies the executable to ~/.local/bin/.

```bash
# Homebrew (macOS/Linux)
brew tap tenatarika/tap
brew install vex

# From source (any platform with a Rust toolchain)
git clone https://github.com/tenatarika/vex.git
cd vex
cargo build --release
cp target/release/vex ~/.local/bin/

```

--------------------------------

### Install vex MCP for any agent

Source: https://github.com/tenatarika/vex/blob/main/README.md

Install the vex MCP server for one, all, or a preview of supported agents using the vex CLI.

```bash
vex mcp install --agent cursor       # or any of: claude-code, codex-cli, windsurf, cline, continue, zed
vex mcp install --agent all          # fan out across every supported agent
vex mcp install --agent cursor --dry-run   # preview the post-merge config without writing
```

--------------------------------

### Install vex on Linux using the pre-built archive

Source: https://github.com/tenatarika/vex/blob/main/README.md

Download the pre-built Linux binary (x86_64, glibc-linked) from the GitHub release, extract it, and move it to a directory on PATH. The final command verifies the installation. For older glibc or musl-based distros, or aarch64 Linux, build from source instead.

```bash
curl -L https://github.com/tenatarika/vex/releases/latest/download/vex-x86_64-unknown-linux-gnu.tar.gz | tar -xz
mv vex ~/.local/bin/      # or: sudo mv vex /usr/local/bin/
vex --version

```

--------------------------------

### GPU diagnostic and shell completion examples

Source: https://github.com/tenatarika/vex/blob/main/README.md

Shows how to probe GPU execution providers and persist a working device, plus how to generate shell completions for zsh.

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

```bash
vex completions zsh > ~/.zfunc/_vex
```

--------------------------------

### Install and configure vex-mcp for Claude Code MCP

Source: https://github.com/tenatarika/vex/blob/main/README.md

Setup for the vex MCP server: download a prebuilt binary for your platform or build from source with `cargo build --release -p vex-mcp`, then configure Claude Code by adding an MCP server entry in `~/.claude/claude_desktop_config.json` with `VEX_ROOT` and `VEX_DEVICE` env vars. `VEX_DEVICE` (v1.16.0) selects GPU execution provider when built with gpu-cuda/gpu-directml/gpu-coreml; `auto` is safe on CPU-only builds. Run `vex gpu` to confirm the execution provider engages.

```bash
# 1. Download the prebuilt for your platform from
#    https://github.com/tenatarika/vex/releases/latest
#    e.g. vex-mcp-aarch64-apple-darwin.tar.gz / vex-mcp-x86_64-pc-windows-msvc.tar.gz
# 2. Extract and put the binary on PATH (or remember the full path).

# Source build (if you prefer or are on an unsupported triple)
cargo build --release -p vex-mcp

# 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"
      }
    }
  }
}
```

--------------------------------

### Install and initialize vex with Homebrew and vex init/index

Source: https://github.com/tenatarika/vex/blob/main/README.md

Install vex via Homebrew and initialize a project: `vex init` creates .vex.toml, `vex index` builds the index. Optional flags: `--semantic` for meaning-based search)Skip or include `--history` for archaeology queries (v1.15.0/v1.16.0). Shown in a fenced Bash block under 'Claude Code (CLI Integration)'.

```bash
# Install vex
brew tap tenatarika/tap && brew install vex

# In your project
cd /path/to/project
vex init              # create .vex.toml
vex index             # build index (add --semantic for meaning-based search;
                      # add --history for `vex history <Symbol>` archaeology queries — v1.15.0/v1.16.0)
```

--------------------------------

### Vex command examples for common search operations

Source: https://github.com/tenatarika/vex/blob/main/README.md

A set of example commands demonstrating various Vex search operations, including exact name lookup, class extraction, usage and caller resolution, fuzzy and semantic search, AST pattern matching, similarity search, duplicate detection, and bundling. The commands show expected performance metrics like '4ms' and '~4ms' for some operations.

```bash
$ vex check "TelemetryProcessor"           # 4ms — does it exist? where? (exact name)
$ vex show "TelemetryProcessor"            # extract the class body (not the whole file)
$ vex usages "Config" --strict             # who references this symbol? (binder-resolved, no noise)
$ vex callers "process_event"              # who calls this function? (~4ms; covers module-scope + Python/Java decorators)
$ vex implementations "BaseService"        # who extends/implements this?
$ vex search "timeout retry"               # fuzzy / multi-word — BM25 finds rare body terms
$ vex search "handle alert" --semantic     # find by meaning, not just name
$ vex pattern 'fn $NAME($$$) -> Result'    # AST pattern matching (like ast-grep)
$ vex similar "PaymentService"             # semantically close symbols
$ vex duplicates --threshold 0.95          # near-duplicate pairs
$ vex bundle --mode symbol --symbol Foo    # body + callers + callees + similar in 1 call
```

--------------------------------

### Homebrew install block with gpu-coreml feature

Source: https://github.com/tenatarika/vex/blob/main/docs/GPU_SUPPORT.md

Homebrew formula install block for the --HEAD (source) branch. Passes gpu-coreml on macOS to match the GPU bottle; Linux --HEAD stays CPU. Requires an elevated shell for self-update when installed under C:\Program Files\.

```ruby
def install
  if build.head?
    args = std_cargo_args
    args += ["--features", "gpu-coreml"] if OS.mac?
    system "cargo", "install", *args
  else
    bin.install "vex"
  end
end
```

--------------------------------

### Sample .vex.toml configuration file

Source: https://github.com/tenatarika/vex/blob/main/README.md

Example .vex.toml file with commented defaults for all configuration options. Options include exclude globs, output format, semantic mode, auto-update, async update, GPU device selection, embedder model, and VCS backend. CLI flags override these values; environment variables act as global defaults.

```toml
# .vex.toml

# Glob patterns to exclude from indexing (gitignore syntax, on top of .gitignore)
exclude = [
    "vendor/**",
    "node_modules/**",
    "*.generated.go",
]

# Output format — "compact" (default since v1.10.1; single-line records),
# "text" (verbose multi-line), or "json" (envelope for MCP / tools).
# format = "text"

# Enable semantic embeddings by default
semantic = true

# Automatically update index before search if stale
# auto_update = false

# With auto_update, refresh in the background rather than blocking the query:
# answers come from the index on disk, the response is flagged stale, and the
# rebuild lands for the next query. Trades freshness for latency.
# async_update = false

# 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"/
# "coreml". `gpu = true/false` is shorthand for auto/cpu. See GPU Acceleration.
# device = "auto"
# gpu = true

# Embedder model: minilm-l6-v2 (default), jina-code, bge-base-en-v1.5,
# bge-large-en-v1.5, mxbai-large. Changing it requires a reindex.
# Set globally across projects with the VEX_EMBEDDER env var (this file wins).
# embedder = "minilm-l6-v2"

# VCS backend for diff-scoping (--since/--since-branched/--changed-only).
# "auto" (default) detects .git/.svn/.arc; "git" | "none" | "arc" | "svn".
# git, arc (Yandex Arc), and svn (Subversion) are all functional backends;
# svn declines --since-branched (no merge-base). "none" disables diff-scoping.
# Overridden by the --vcs flag and the $VEX_VCS env var. See docs/VCS-BACKENDS.md.
# vcs = "auto"
```

--------------------------------

### vex usages command output for MediaController

Source: https://github.com/tenatarika/vex/blob/main/docs/LIMITATIONS.md

Example command and output showing the result of `vex usages MediaController` on T1 languages. If it returns `[]`, a stale index from before v1.8.0 is likely; re-run `vex index`.

```bash
$ vex usages MediaController
media_server/video.py:3
media_server/audio.py:3
...
```

--------------------------------

### Cross-language search with vex grep and show

Source: https://github.com/tenatarika/vex/blob/main/.claude/skills/vex/SKILL.md

Use vex grep with stable string prefixes to find related symbols across language boundaries, then pivot to structure with vex show. The example shows searching for route paths, queue topics, and proto messages, then showing the handler.

```bash
vex grep 'api/v1/invoices'        # route path — matches the TS call site AND the Go route
vex grep 'invoice.created'        # queue topic
vex grep 'CreateInvoiceRequest'   # proto message → its generated stubs in every language
vex show InvoiceHandler           # then pivot to structure once you know the name
```

--------------------------------

### Set up and run cargo-fuzz targets for fuzzing

Source: https://github.com/tenatarika/vex/blob/main/README.md

Installs cargo-fuzz, generates seed corpora for all targets, and runs twelve fuzz targets with a nightly toolchain. Each target exercises a different unsafe path or parser (e.g., fuzz_index_reader, fuzz_pattern_parser). Running requires nightly and uses libFuzzer with AddressSanitizer.

```bash
# Install (once)
cargo install cargo-fuzz

# Generate seed corpus for every target
bash fuzz/generate_seeds.sh

# Run (requires nightly)
RUSTUP_TOOLCHAIN=nightly cargo fuzz run fuzz_index_reader        -- -max_total_time=120
RUSTUP_TOOLCHAIN=nightly cargo fuzz run fuzz_refs_fst            -- -max_total_time=60
RUSTUP_TOOLCHAIN=nightly cargo fuzz run fuzz_symbol_fst          -- -max_total_time=60
RUSTUP_TOOLCHAIN=nightly cargo fuzz run fuzz_bloom_load          -- -max_total_time=60
RUSTUP_TOOLCHAIN=nightly cargo fuzz run fuzz_pattern_parser      -- -max_total_time=60
RUSTUP_TOOLCHAIN=nightly cargo fuzz run fuzz_manifest_load       -- -max_total_time=60
RUSTUP_TOOLCHAIN=nightly cargo fuzz run fuzz_marker_load         -- -max_total_time=60
RUSTUP_TOOLCHAIN=nightly cargo fuzz run fuzz_tokenize_document   -- -max_total_time=60
RUSTUP_TOOLCHAIN=nightly cargo fuzz run fuzz_hash_index_load     -- -max_total_time=60
RUSTUP_TOOLCHAIN=nightly cargo fuzz run fuzz_incremental_hnsw    -- -max_total_time=60
RUSTUP_TOOLCHAIN=nightly cargo fuzz run fuzz_rename_chains_load  -- -max_total_time=60
RUSTUP_TOOLCHAIN=nightly cargo fuzz run fuzz_state_load          -- -max_total_time=60
```

--------------------------------

### Python class inheritance example for T1 AST walk

Source: https://github.com/tenatarika/vex/blob/main/docs/LIMITATIONS.md

Shows how T1 AST walk captures inheritance refs like `MediaController` in Python class definitions. Used to illustrate the repro for `vex usages MediaController`.

```python
class MediaController: ...

class VideoController(MediaController): ...   # T1 AST walk captures `MediaController`
class AudioController(MediaController): ...   # same
```

--------------------------------

### vex mcp install --agent <id>

Source: https://github.com/tenatarika/vex/blob/main/integrations/README.md

Use the auto-installer (v1.15.0+) to configure MCP servers for supported agents. It reads existing config, merges a vex server entry without disturbing siblings, and writes back atomically. The --dry-run flag previews changes without writing.

```bash
vex mcp install --agent cursor               # or: claude-code, codex-cli, windsurf, cline, continue, zed
vex mcp install --agent all                  # configure every supported agent
vex mcp install --agent cursor --dry-run     # preview without writing
vex mcp uninstall --agent cursor             # remove the entry
vex mcp list                                 # show current entries per agent
```

--------------------------------

### mode_hints per-mode shape (symbol, pr-impact, project)

Source: https://github.com/tenatarika/vex/blob/main/docs/MCP-SCHEMA.md

Shows the JSONC shape of mode_hints for each mode: symbol, pr-impact, and project. Each block is a separate example for the corresponding mode.

```jsonc
// mode: symbol
{
  "callers_count": 2, "callees_count": 2, "similar_count": 0,
  "callers_truncated": false, "callees_truncated": false, "similar_truncated": false,
  "has_call_graph": true, "has_vectors": false,
  "empty_reason": null | "symbol_not_found"
}
```

```jsonc
// mode: pr-impact
{
  "base": "HEAD", "depth": 2,
  "changed_count": 1, "transitive_caller_count": 2, "test_count": 1,
  "tests_truncated": false, "unreachable_changes": [],
  "empty_reason": null | "no_changes"
}
```

```jsonc
// mode: project
{
  "scoring": "reverse_indegree", "top_n": 30, "path_glob": null,
  "total_ranked_symbols": 12, "has_call_graph": true,
  "empty_reason": null | "no_call_graph" | "no_call_edges" | "path_glob_filtered_all"
}
```

--------------------------------

### Sample `vex modules` text output with cluster details

Source: https://github.com/tenatarika/vex/blob/main/README.md

Example text output from `vex modules` on this repository. It lists three clusters with their id, path prefix, symbol count, cohesion, and top hubs; the header shows the algorithm, gamma, cluster counts, and unclustered/not-eligible counts. Cluster ids are ordinals in the section, not ranks.

```text
Modules — leiden-cpm/1 γ=1/8 · 475 clusters (≥3, showing 3) · 1,469 unclustered · 1,464 not eligible
  #60  src/cli/                     39 symbols  cohesion 0.49  hubs: OutputFormat, print_envelope, default_meta_for
  #23  crates/vex-mcp/src/tools/    38 symbols  cohesion 0.68  hubs: opt_bool, build_command, opt_u64
  #286 src/pattern/matcher/tests.rs 32 symbols  cohesion 0.78  hubs: parse_pattern, find_matches, Segment
```

--------------------------------

### Bundle queries with vex bundle (symbol, pr-impact, project)

Source: https://github.com/tenatarika/vex/blob/main/README.md

Bundle commands: combine 4 round-trips into 1 envelope. symbol mode gets body + callers + callees + similar; pr-impact mode gets changed symbols + transitive callers + tests; project mode gets top-N by reverse call-graph indegree. Available in v1.9, Phase 13.2.

```bash
vex bundle --mode symbol --symbol PaymentService
```

```bash
vex bundle --mode pr-impact --base origin/main
```

```bash
vex bundle --mode project --top-n 30
```

--------------------------------

### MCP response with deprecated_args

Source: https://github.com/tenatarika/vex/blob/main/docs/MCP-SCHEMA.md

Example response from an MCP tool call when a legacy field like `name` is used. The `_meta.deprecated_args` array lists each legacy name the client sent. Clients that don't read `_meta` see the same `content` array as before.

```json
{
  "content": [{ "type": "text", "text": "[...]" }],
  "_meta": {
    "deprecated_args": ["name"]
  }
}
```

--------------------------------

### Python decorator repro (Phase 14.2)

Source: https://github.com/tenatarika/vex/blob/main/docs/LIMITATIONS.md

Shows a Python decorator `@app.get` on a function, which now emits a forward edge `list_items → get`. The `vex callers get` output demonstrates the reported caller.

```python
@app.get("/items")
def list_items(): ...   # ← Phase 14.2: edge list_items → get
```

```shell
$ vex callers get
list_items  media_server/main.py:411
```

--------------------------------

### Response shape JSONC example

Source: https://github.com/tenatarika/vex/blob/main/docs/MCP-SCHEMA.md

Shows the JSONC response structure for the bundle tool, including protocol_version, capabilities, _meta with index_age_ms and diff_filter, and results with mode and items. The _meta is invisible to the LLM per MCP spec.

```jsonc
{
  "protocol_version": "v1",
  "capabilities": { "signals": true, "bundle_modes": [...], ... },
  "_meta": {
    "vex.dev/index_age_ms": 1200,
    // pr-impact only:
    "vex.dev/diff_filter": {
      "scope": "pr-impact:HEAD",
      "changed_paths": ["src/lib.rs"],
      "retained": 4,
      "dropped": 0
    }
  },
  "results": {
    "mode": "symbol" | "pr-impact" | "project",
    "items": [ /* see role enum below */ ],
    "mode_hints": { /* per-mode keys, see below */ }
  }
}
```

--------------------------------

### Use `vex modules` to list and filter symbol clusters

Source: https://github.com/tenatarika/vex/blob/main/README.md

Shows three example invocations of `vex modules`: plain, with filtering/sorting, and for a single symbol. The first line lists clusters of at least 3 symbols largest first; the second filters members by `--include 'src/**'`, sets `--members 5`, and sorts by cohesion; the third prints the cluster of the named symbol with its members.

```bash
vex modules                         # clusters of >= 3 symbols, largest first
vex modules --members 5 --sort cohesion --include 'src/**'
vex modules IndexReader             # the cluster of one symbol, with its members
```

--------------------------------

### Per-channel attribution aggregate output (by_channel)

Source: https://github.com/tenatarika/vex/blob/main/docs/RANKING-EVAL.md

Example aggregate output from a 13.12.1 run against vex's own source tree (without --semantic). Shows per-channel top1_count and top_k_count within the EVAL_K window, illustrating that Hybrid fusion contributes most top-1 results while Structural results are always upgraded to Hybrid.

```text
By channel:
  Hybrid       top1=13  top10=31    ← fusion does real work; 81% of top-1s
  Bm25         top1=1   top10=99    ← pulls a lot, rarely the best
  Fuzzy        top1=2   top10=7
  Structural   top1=0   top10=1     ← always upgraded to Hybrid via fusion
```

--------------------------------

### TypeScript decorator repro (Phase 14.2.1)

Source: https://github.com/tenatarika/vex/blob/main/docs/LIMITATIONS.md

Shows a TypeScript method-level decorator `@Get` that emits an edge `handler → Get`.

```typescript
class C {
    @Get("/x")
    handler() { ... }   // ← Phase 14.2.1: edge handler → Get
}
```

--------------------------------

### vex init

Source: https://github.com/tenatarika/vex/blob/main/README.md

Initialize a default configuration file.

```APIDOC
## vex init

### Description
Create a default `.vex.toml` config file in the project root.

### Method
CLI

### Endpoint
`vex init`

```

--------------------------------

### Initialize .vex.toml configuration

Source: https://github.com/tenatarika/vex/blob/main/README.md

Generates a .vex.toml file with commented defaults. Run in the project root to create the configuration file.

```bash
vex init  # generates .vex.toml with commented defaults
```

--------------------------------

### Historical symbol view with vex index --history and vex history

Source: https://github.com/tenatarika/vex/blob/main/README.md

Historical view of a symbol: build the persistent history sidecar once with vex index --history, then query every version reachable from HEAD (~10ms), get unified diffs between consecutive versions, filter by date/author/kind, and get exact commit set for each blob location (revert-aware). Available in v1.15.0; expanded in v1.16.0.

```bash
vex index --history
```

```bash
vex history "PaymentService"
```

```bash
vex history "PaymentService" --diff
```

```bash
vex history "Foo" --since 2026-01-01 --author alice --kind function
```

```bash
vex history "deleted_symbol" --exact-presence
```

--------------------------------

### Run vex eval with options (--min-ndcg, --json, --bench)

Source: https://github.com/tenatarika/vex/blob/main/docs/RANKING-EVAL.md

Run the ranking evaluation harness against the existing index in the current working directory. Use --min-ndcg to fail with a non-zero exit if mean nDCG@10 drops below the threshold, --json to emit JSON for tooling, and --bench to specify a custom golden set. The harness never builds an index; running it without an existing index is an error, so pair it with vex index or vex update in CI.

```bash
# Run the harness against the current index in the cwd.
vex eval

# Fail with non-zero exit if mean nDCG@10 drops below a threshold.
vex eval --min-ndcg 0.85

# Emit JSON for tooling.
vex eval --json

# Use a custom golden set (e.g. one tuned to a downstream repo).
vex eval --bench path/to/queries.toml
```

--------------------------------

### Show file structure outline with vex outline

Source: https://github.com/tenatarika/vex/blob/main/README.md

Display the file structure outline for a given source file.

```bash
vex outline src/main.rs
```

--------------------------------

### Run unit and integration tests with cargo test and clippy

Source: https://github.com/tenatarika/vex/blob/main/README.md

Runs the full test suite (unit, integration, property-based, adversarial) and Clippy with warnings denied. The comment indicates 1973 tests and a zero-warnings policy.

```bash
cargo test                    # 1973 tests — unit, integration, property-based, adversarial
cargo clippy -- -D warnings   # zero warnings policy
```

--------------------------------

### Staleness warning output

Source: https://github.com/tenatarika/vex/blob/main/README.md

Example output when the index is stale: vex prints a warning suggesting to run `vex update`. The warning triggers when the git HEAD has changed since indexing, or for non-git repos when the mtime changes and the content hash differs.

```text
$ vex search "Config"
Warning: index may be stale (HEAD changed). Run `vex update`.
```

--------------------------------

### Module-scope call site repro (Python)

Source: https://github.com/tenatarika/vex/blob/main/docs/LIMITATIONS.md

Shows a module-scope call to `create_app` that is now attributed to the synthetic `<module:media_server/main.py>` caller. The `vex callers create_app` output demonstrates the reported caller and line number.

```python
# media_server/main.py
def create_app(): ...

app = create_app()   # ← now reported as <module:media_server/main.py>
```

```shell
$ vex callers create_app
<module:media_server/main.py>  media_server/main.py:411
```

--------------------------------

### impact tool results shape

Source: https://github.com/tenatarika/vex/blob/main/docs/MCP-SCHEMA.md

Example `results` shape returned by the `impact` MCP tool (v1.20.0). The verdict is `safe`, `unsafe`, or `uncertain`; `unsafe` occurs when `strict_refs > 0` or `call_graph_callers > 0`. `vex impact` always exits 0, so agents must read the verdict from the envelope.

```json
{
  "symbol": "build_mcp_response",
  "verdict": "unsafe",
  "verdict_explanation": "binder/graph confirmed real usage (strict_refs=6, call_graph_callers=3). Do not delete without rewriting call sites.",
  "channels": {
    "strict_refs":        { "available": true,  "count": 6, "sample": [{"path": "…", "line": 475}, …], "truncated": false },
    "fst_refs":           { "available": true,  "count": 7, "sample": [...], "truncated": false },
    "grep_word_boundary": { "available": true,  "count": 8, "sample": [...], "truncated": false },
    "call_graph_callers": { "available": true,  "count": 3, "sample": [...], "truncated": false }
  }
}
```

--------------------------------

### Cross-language request tracing with vex grep, show, and callers

Source: https://github.com/tenatarika/vex/blob/main/docs/COOKBOOK.md

Search for a shared string across language boundaries using vex grep with --format compact, then pivot to structural commands (vex show, vex callers) once the handler name is known. The comments show how route parameters differ per framework, so match the stable prefix rather than the whole path.

```bash
# The literal both sides carry
vex grep 'v1/invoices' --format compact

# Route params differ per framework — match the stable prefix, not the whole path
#   TS:     fetch(`/api/v1/invoices/${id}`)
#   Go:     r.Get("/api/v1/invoices/{id}", h.Get)
#   Python: @app.get("/api/v1/invoices/{invoice_id}")
vex grep 'api/v1/invoices' --format compact

# Then pivot to structure once you know the handler's name
vex show InvoiceHandler
vex callers InvoiceHandler
```

--------------------------------

### Configure multi-codebase vex-mcp servers with VEX_ROOT

Source: https://github.com/tenatarika/vex/blob/main/docs/COOKBOOK.md

Configure two vex-mcp server entries in the agent config, one per repository, with distinct names (vex-api and vex-client) and VEX_ROOT environment variables to avoid tool name collisions. The agent sees tools like vex-api.search and vex-client.search (exact namespacing is agent-specific).

```jsonc
{
  "mcpServers": {
    "vex-api":    { "command": "/path/to/vex-mcp", "env": { "VEX_ROOT": "/repos/api"    } },
    "vex-client": { "command": "/path/to/vex-mcp", "env": { "VEX_ROOT": "/repos/client" } }
  }
}
```

--------------------------------

### signals block with bm25_score and semantic_cosine

Source: https://github.com/tenatarika/vex/blob/main/docs/MCP-SCHEMA.md

Example of the signals block on a search result row, showing the two new raw-score fields bm25_score and semantic_cosine alongside the existing rank ordinals. bm25_score is optional and None when the row did not appear in the BM25 channel; semantic_cosine is optional and None when the row did not appear in the semantic channel or the channel did not run.

```json
{
  "fst_hit": true,
  "bm25_rank": 2,
  "bm25_score": 3.033,
  "semantic_rank": 0,
  "semantic_cosine": 0.812
}
```

--------------------------------

### Multi-repo workspace commands with vex --workspace

Source: https://github.com/tenatarika/vex/blob/main/README.md

Multi-repo commands: treat a set of sibling repos as one workspace. index builds every member of .vex-workspace.toml; search fans out with results grouped by repo; usages with --strict requires a v7 index; watch keeps every member incrementally fresh. Available in v1.22.0.

```bash
vex index --workspace
```

```bash
vex search "RetryPolicy" --workspace
```

```bash
vex usages Config --strict --workspace
```

```bash
vex watch --workspace
```

--------------------------------

### Device::resolve precedence for CLI, config, and env

Source: https://github.com/tenatarika/vex/blob/main/docs/GPU_SUPPORT.md

Resolves the execution device for the index path. Precedence: CLI `--device`, CLI `--gpu`/`--no-gpu`, `.vex.toml` `device`, `.vex.toml` `gpu`, `VEX_DEVICE` env, then `default_device()` (Auto in GPU builds, Cpu otherwise). MCP reuses this path directly.

```rust
    /// Resolve the device for the **index path**. Precedence (first present wins):
    ///   1. CLI `--device <x>`            (explicit EP override)
    ///   2. CLI `--gpu` / `--no-gpu`      (boolean: Auto / Cpu)
    ///   3. `.vex.toml` `device = "<x>"`
    ///   4. `.vex.toml` `gpu = true|false`
    ///   5. `VEX_DEVICE` env
    ///   6. default: `default_device()` — **Auto** in a GPU-compiled binary,
    ///      **Cpu** otherwise.
    ///
    /// MCP passes its `gpu` / `device` args straight through as the CLI flags,
    /// so it reuses this exact path — no separate resolution.
    pub fn resolve(
        cli_device: Option<&str>,
        cli_gpu: Option<bool>,
        cfg_device: Option<&str>,
        cfg_gpu: Option<bool>,
    ) -> Result<Self> {
        if let Some(v) = cli_device { return Device::parse(v); }
        if let Some(g) = cli_gpu { return Ok(if g { Device::Auto } else { Device::Cpu }); }
        if let Some(v) = cfg_device { return Device::parse(v); }
        if let Some(g) = cfg_gpu { return Ok(if g { Device::Auto } else { Device::Cpu }); }
        match std::env::var("VEX_DEVICE") {
            Ok(v) => Device::parse(&v),
            Err(_) => Ok(default_device()), // compile-time default
        }
    }
}
```

--------------------------------

### vex pattern examples: named captures, && / || composition, --why

Source: https://github.com/tenatarika/vex/blob/main/README.md

Four sample invocations of the `vex pattern` CLI. The first uses named ellipses `$$ARGS` and `$$$BODY` to capture a function's parameter list and body; the second combines `struct $S` and `impl $S` with `&&` to require both shapes for the same type in one file; the third uses `||` to match either an interface or class with the same name; the fourth shows `--why` to report which mode (indexed prefilter or live-scan) was used and what narrowing occurred, with stderr redirected to `trace.json`.

```bash
# Multi-line function body with named captures
vex pattern 'fn $NAME($$ARGS) -> Result<$T, $E> { $$$BODY }' --lang rust

```

```bash
# Both struct and impl for the same type in one file
vex pattern 'struct $S && impl $S' --lang rust

```

```bash
# Interface OR class with the same name
vex pattern 'interface $N || class $N' --lang typescript

```

```bash
# See which mode and what narrowing happened
vex pattern 'fn $N($$$)' --lang rust --why 2>trace.json

```

--------------------------------

### Core vex CLI commands (index, search, show, similar)

Source: https://github.com/tenatarika/vex/blob/main/README.md

Command-line invocations for indexing, hybrid search, symbol extraction, and semantic similarity lookup. These are the primary vex commands with their core flags.

```bash
vex index [--path .] [--semantic] [--embedder ID] [--history [--history-depth N]]
```

```bash
vex search <query> [--semantic] [--no-bm25] [--limit N] [--kind def,fn,…] [--visibility V] [--async-only] [--code-only] [--exclude-generated] [--why]
```

```bash
vex show <symbol> [--limit N] [--context N] [--kind fn] [--visibility V] [--async-only] [--signature-only | --head N | --no-body]
```

```bash
vex similar <name> [--limit N] [--min-score T] [--explain]
```