vex

Vex

Fast hybrid structural + semantic code search. Vector + index.

Why Vex? · How It Compares · Installation · Quick Start · Commands · Configuration · How Search Works · Benchmarks · Supported Languages · Integration · Testing · Architecture

$ 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' --lang rust # 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

Pick the right tool: vex check for "does Foo exist?", vex search for "find me something about retries". search is a *ranked blend* — it surfaces neighbors (callers / imports) when no symbol literally matches, which is great for exploration and wrong for exact-name lookup. v1.15.0 prints a stderr hint when an identifier-shaped search returns 0 FST hits.

Why Vex?

• ~4-5ms search after indexing — FST-based O(query_len) lookup, not O(symbols); constant regardless of project size. Requires a pre-built index. Indexing is a one-time cost (hundreds of ms on typical projects) and builds *more* than a plain text index — FST + BM25 + call graph + type-hierarchy + trigram skip-index — so it trades a slower build for far cheaper, richer queries (see Benchmarks)
• 3-channel hybrid search — structural FST (names) + BM25 (rare body terms) + semantic HNSW (meaning), fused via Reciprocal Rank Fusion. Find symbols when you don't know the exact name AND when generic semantic-only search would be too noisy
• Persistent call graph — vex callers/vex callees read from a persistent index built at index time (~4ms), not a live tree-sitter scan (seconds): callers is a name-keyed FST, callees is a dense CSR index (v9+). Module-scope expressions are reported via synthetic callers (Phase 14.1); Python + Java function/method decorators (Phase 14.2), Kotlin annotations + C# method/constructor attributes (Phase 14.2.2), and TypeScript method decorators + Rust outer attributes (Phase 14.2.1) emit forward edges to their targets. Class-level decorators remain invisible — see docs/LIMITATIONS.md
• Pluggable embedder — Embedder trait + registry; swap MiniLM-L6-v2 for future code-specific models (BGE, CodeBERT) without touching call sites
• Token-efficient — compact output saves typically 6x fewer tokens than grep on average lookups (up to 217x on minified JS/CSS); vex show extracts just the symbol body instead of the whole file
• 20 languages indexed via tree-sitter, with three coverage tiers: type-aware `--strict usages` on 8 binder languages (Rust / TypeScript / Python / C# / C++ / Go / Java / Kotlin); indexed pattern prefilter on 16 T1+T2a languages; baseline structural + semantic search on all 20 (see Supported Languages for the matrix)
• Single binary, zero config — no LSP servers, no databases, no Docker. Just vex index && vex check Foo

What Vex isn't

vex is a static-analysis indexing tool, not a language server. Set expectations honestly:

• Not an LSP replacement. No go-to-definition into third-party packages, no rename refactoring, no type-checking, no hover docs. For those, keep your LSP.
• `vex search` is a ranked blend, not an exact-name lookup. Structural FST + BM25 + semantic fused via RRF return *relevance-ordered* results — when no symbol literally named Foo lives in the index (imported from a dependency, deleted, typo), BM25 may surface callers / imports as if they were the definition. For exact-symbol questions ("does it exist?", "show me the body", "who calls it?") use vex check Foo / vex show Foo / vex usages Foo --strict — they bypass the ranker. v1.15.0 prints a one-line stderr hint when an identifier-shaped query gets zero FST hits.
• No dynamic-dispatch visibility. Decorator routing (@router.get("/path")), string-resolved factories (uvicorn.run("main:app")), reflection (getattr(obj, name)()), and macro-expanded references are all invisible to every vex command. vex grep '\bname\b' is the textual escape hatch.
• `vex callers` has uneven coverage outside function scope. Module-level expressions like app = create_app() are reported via synthetic callers (Phase 14.1). Python + Java function/method decorators (Phase 14.2), Kotlin annotations + C# method/constructor attributes (Phase 14.2.2), and TypeScript method decorators + Rust outer attributes on fns/methods (Phase 14.2.1) emit forward edges — vex callers GetMapping lists every Spring handler, vex callers HttpGet every ASP.NET action, vex callers test every #[tokio::test]. Class-level decorators (14.6) remain on the roadmap.
• `vex usages` quality varies by language. 8 binder-supported languages get refactor-grade --strict refs; the other 11 use an identifier scanner with a higher false-positive rate.

See docs/LIMITATIONS.md for the full coverage matrix, concrete repros, and recommended workarounds per query type. Read it before evaluating vex on a Python/FastAPI/Django codebase — the framework patterns are the most-flagged gaps.

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).

Installation

# Install script (macOS arm64, Linux x86_64): vex + vex-mcp into ~/.local/bin

curl -fsSL https://raw.githubusercontent.com/tenatarika/vex/main/install.sh | sh

Windows (PowerShell): vex + vex-mcp into %LOCALAPPDATA%\Programs\vex, added to PATH

irm https://raw.githubusercontent.com/tenatarika/vex/main/install.ps1 | iex

Homebrew (macOS/Linux)

brew tap tenatarika/tap brew install vex

cargo-binstall: prebuilt release binaries, no compiler needed

cargo binstall vex-search # → ~/.cargo/bin/vex cargo binstall vex-search-mcp # → ~/.cargo/bin/vex-mcp (MCP server)

crates.io (compiles from source; the crate is vex-search, the binary is vex)

cargo install vex-search --locked # → ~/.cargo/bin/vex cargo install vex-search-mcp --locked # → ~/.cargo/bin/vex-mcp (MCP server)

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/

The install script takes VEX_VERSION=1.28.0 to pin a release, VEX_INSTALL_DIR to install elsewhere and VEX_NO_MCP=1 to skip vex-mcp. On other platforms, musl or glibc older than 2.34 it stops and points to a source build. cargo binstall uses the same release archives where they exist and builds from source elsewhere; on Windows it installs vex.exe without the archive's DirectML.dll, so GPU indexing falls back to CPU.

What cargo install vex-search (and any source build) needs:

• Network at build time: the build downloads a prebuilt ONNX Runtime. Prebuilts exist only for aarch64-apple-darwin, x86_64/aarch64-unknown-linux-gnu and x86_64/aarch64-pc-windows-msvc; on any other target (Intel macOS, musl, …) point ORT_LIB_LOCATION at a local ONNX Runtime build.
• A C/C++ toolchain (Xcode Command Line Tools, build-essential, or MSVC Build Tools) for the tree-sitter grammars. GCC must be 12 or newer: GCC 11 (the default on Ubuntu 22.04) can't compile the bundled numkong vector kernels. Install gcc-12 g++-12 and build with CC=gcc-12 CXX=g++-12 cargo install vex-search --locked.
• Linux: `libssl-dev` and `pkg-config` (Fedora: openssl-devel). The HTTP stack links OpenSSL through native-tls.
• The first vex index --semantic downloads the ~86 MB embedding model; structural search needs no download.
• vex-search-mcp only installs the MCP server. It runs the vex CLI, so install vex-search too and keep vex on PATH, or set VEX_BIN to its full path.

Linux

Pre-built vex ships in every GitHub Release for x86_64-unknown-linux-gnu. It needs glibc 2.34 or newer (Ubuntu 22.04+, Debian 12+, RHEL / Rocky / AlmaLinux 9+); on older systems build from source:

curl -fsSL https://raw.githubusercontent.com/tenatarika/vex/main/install.sh | sh

or by hand:

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

Built on the ubuntu-22.04 GitHub runner (glibc-linked, libstdc++ linked in). For older glibc distros, musl-based distros (Alpine, NixOS without nix-ld), or aarch64 Linux (Graviton, Pi 5, Ampere) — build from source via cargo build --release.

Windows

Pre-built vex.exe ships in every GitHub Release. The quickest way to install it, from PowerShell:

irm https://raw.githubusercontent.com/tenatarika/vex/main/install.ps1 | iex

It puts vex.exe, vex-mcp.exe and DirectML.dll in %LOCALAPPDATA%\Programs\vex (a per-user folder) and adds it to your user PATH. VEX_VERSION, VEX_INSTALL_DIR and VEX_NO_MCP=1 work as in install.sh. To install by hand instead:

1. Download vex-x86_64-pc-windows-msvc.tar.gz from the [la