alexei.dolgolyov/claude-code-facts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(vex): split vex into its own reference, refresh for v1.16.0

Browse Source 
- Add vex.md: install (prebuilt binaries + self-update), GPU/CUDA setup,
  jina-code+CUDA recommendation (CUDA essential, too slow on CPU),
  vex mcp install, full command set (bundle/paths/reachable/diff/history,
  search scope+metadata filters), CLAUDE.md integration, caveats
- Shrink claude-code-tools.md section vex to a blurb + links
- Note v1.16.0 capabilities in the vex-vs-ast-index benchmark (not re-benchmarked)
- README: bump date, index vex.md, refresh vex descriptions
This commit is contained in:
Admin
2026-06-11 01:11:26 +03:00
parent cd0d984930
commit 4c3b0188d8
4 changed files with 227 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files
claude-code-tools.md
+4 -92
View File
@@ -70,99 +70,11 @@ Fast code search skill for Claude Code — find classes, symbols, usages, implem
### vex
Fast hybrid code search — combines tree-sitter AST parsing, FST symbol lookup, BM25 body search, and optional ONNX semantic embeddings. Ships as a CLI (`vex search`, `vex usages`, `vex callers`, `vex similar`, `vex duplicates`, `vex pattern`, etc.) plus an optional MCP server (`vex-mcp`) that exposes the same operations to Claude Code as ~17 structured tools. Useful as a peer or replacement for AST Index when you want semantic / concept-level search in addition to exact symbol lookup.
Fast hybrid code search — tree-sitter AST parsing, FST symbol lookup, BM25 body search, a persistent call graph, optional ONNX semantic embeddings, and (v1.16) a query-time git-history walker. Ships as a CLI plus an optional `vex-mcp` MCP server exposing 20+ structured tools to Claude Code. A strong peer or replacement for AST Index when you want semantic / concept-level search, call-graph navigation, and symbol-level git archaeology alongside exact symbol lookup.
- **Repository:** <https://github.com/tenatarika/vex>
- **Languages:** 18+ via tree-sitter — Python, TypeScript/JavaScript, Go, Rust, Java, Kotlin, C#, Ruby, Swift, C++, PHP, Bash, Lua, CSS, HTML, YAML, TOML, SQL, Markdown.
- **Install (Linux/macOS):**
```bash
brew tap tenatarika/tap && brew install vex
```
Latest release also ships prebuilt tarballs for `linux-x86_64` and `darwin-aarch64`.
- **Install (Windows — build from source, ~3 min):**
As of v1.5.0 there is **no prebuilt Windows binary** in the release assets, so a Rust toolchain (≥1.80) is required:
```bash
git clone https://github.com/tenatarika/vex.git "$HOME/Documents/vex"
cd "$HOME/Documents/vex"
cargo build --release --workspace
cp target/release/vex.exe target/release/vex-mcp.exe "$HOME/.cargo/bin/"
```
`~/.cargo/bin/` (i.e. `%USERPROFILE%\.cargo\bin`) is already on PATH on any system with `cargo` installed, so both binaries become globally callable immediately.
- **Per-project bootstrap:**
```bash
cd <your-project>
vex init # creates .vex.toml
vex index --path . # plain index, sub-second, no downloads
# or, for semantic / concept-level search:
vex index --path . --semantic # downloads ~86 MB ONNX model on first run
```
Recommended `.vex.toml` for serious use:
```toml
semantic = true # enable meaning-based search (vex similar, vex duplicates, --semantic queries)
auto_update = true # incrementally refresh the index before each search
```
- **Register `vex-mcp` with Claude Code (user scope — available across all projects):**
```bash
# Windows
claude mcp add vex -s user -- "$HOME/.cargo/bin/vex-mcp.exe"
# macOS / Linux
claude mcp add vex -s user -- "$HOME/.cargo/bin/vex-mcp"
```
`vex-mcp` defaults `VEX_ROOT` to the current working directory, so a single global registration works for every project — individual tool calls can also override per-call via a `project_root` argument.
- **Key commands / MCP tools:** `search` (symbol + semantic), `show` (full body), `usages`, `callers`, `callees`, `implementations`, `outline`, `pattern` (ast-grep–style structural match), `similar` (semantic, requires `--semantic` index), `duplicates`, `status`, `grep` (regex fallback, no index needed), `update` (incremental reindex).
- **Wire it into `CLAUDE.md` (recommended):**
Installing the binaries and building an index isn't enough — Claude won't reliably prefer `vex` over `Grep`/`Read` unless a `CLAUDE.md` tells it to.
**Start from upstream**, don't duplicate. The vex README maintains a canonical `CLAUDE.md` snippet — see [`README.md` → "CLAUDE.md Integration"](https://github.com/tenatarika/vex#claudemd-integration). Paste it into your **global** `~/.claude/CLAUDE.md` (applies to every project) or a **project-local** `./CLAUDE.md` (overrides global per repo).
**Then graft on these local additions** — they go beyond what upstream covers and are worth keeping wherever you install vex:
1. **MCP server line** — add this near the top of the snippet so Claude knows the MCP route exists:
> Equivalent **MCP tools** are also available via the `vex` MCP server when registered (`claude mcp add vex -s user`) — prefer them inside a Claude Code session for cheaper token output; use the Bash CLI from subagents, hooks, and scripts.
2. **Skip-vex rule** — add to the Rules block:
> **Skip vex** for non-code text — config files (YAML/JSON/TOML), docs, log strings, free-form prose — and for files in languages vex doesn't parse. Fall back to the next tool in the priority chain that's actually capable for the case (typically Grep/Glob for free-form text).
3. **Subagent reminder** — add to the Rules block:
> **Subagents** (Plan/Explore/general-purpose) don't inherit project CLAUDE.md or the parent's MCP toolset — explicitly tell them in the prompt to use `vex` via Bash for code search.
4. **`auto_update` accuracy fix** — upstream says "Run `vex update` after modifying source files if `auto_update` is not enabled." With `auto_update = true` it runs before *each search*, so during a Claude session the manual update is rarely needed. Reword as:
> **Run `vex update` manually after editing** only if `auto_update = false`; with `auto_update = true`, vex auto-refreshes before each search.
5. **`--semantic` cost note** — append to the `vex index --semantic` line in the Indexing block:
> downloads ~86 MB ONNX model on first run, enables `vex search --semantic`, `vex similar`, `vex duplicates`.
**When to put it in global vs project CLAUDE.md:**
- **Global (`~/.claude/CLAUDE.md`)** — preferred default once `vex-mcp` is registered at user scope. Vex becomes the recommendation for every project as soon as the index is built.
- **Project-local (`./CLAUDE.md`)** — for overrides (different fallback chain, monorepo-specific `--filter` paths, language-specific `--kind` defaults, or excluding vex on repos where it isn't set up).
- **Caveats (as of v1.5.0):** vex is a young tool under active development. Known quirks: `implementations` doesn't detect generic-parameterized subclasses (`class Foo(Base[T])`); `usages` is text-flavored and matches inside comments/docstrings; first-time Windows install requires building from source. Verify load-bearing results against `ast-index` or `Grep`. The benchmark notes below capture more specific findings on a real repo.
- **vex vs AST Index — when each wins:** Both tools cover similar ground, but they're not interchangeable. For a point-in-time head-to-head on a real mixed-language repo (Python / Kotlin / TypeScript / JavaScript) with measured latency, quality differences, and version-pinned findings, see [`code-search-vex-vs-ast-index.md`](code-search-vex-vs-ast-index.md). Headline: keep `vex` as primary, fall back to `ast-index changed --base <branch>` for code-review diffs (no vex equivalent) and to `ast-index symbol`/`usages` when vex's textual matches are too noisy.
- **Repository:** <https://github.com/tenatarika/vex> · **Current release:** v1.16.0 (`vex self-update` to upgrade in place).
- **Full reference → [vex.md](vex.md)** — install (prebuilt Windows/macOS/Linux + `self-update`, or build-from-source), **GPU / CUDA acceleration** (strongly prefer `jina-code` + CUDA; it's too slow on CPU), `vex mcp install`, the recommended `.vex.toml`, the full command set (`bundle`, `paths`, `reachable`, `diff`, `history`, search scope/metadata filters), CLAUDE.md integration, and caveats.
- **Benchmark vs AST Index → [code-search-vex-vs-ast-index.md](code-search-vex-vs-ast-index.md)** — point-in-time head-to-head. Headline: keep `vex` primary; fall back to `ast-index changed --base <branch>` for code-review diffs and to `ast-index symbol` / `usages` when you want textual matches.
### Packaged Skills