usages
Find every reference to a symbol across your codebase. Uses scope-resolved references for accurate cross-file callers, reducing noise from comments and string literals.
Instructions
Find every reference to a symbol across the codebase. Prefer over grep for refactor-style find all callers queries — grep on a common identifier returns string-literal and comment noise; usages with strict=true uses the scope-binder to resolve real cross-file refs (Rust/TypeScript/Python/C#/C++). Without strict, runs the legacy refs FST (~4ms) — v1.20.0 also strips the row at the symbol's own definition line and prose mentions in *.md/*.markdown/*.txt/*.rst/*.adoc (override with include_self / include_docs).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| why | No | Surface a JSON trace under `_meta.why`: mode (strict/fst_lookup), mode_legacy (back-compat alias for v1.9.x consumers, removed in v1.12), hits before/after path filter, prefix-suggestion count when no exact hits, def_site_dropped / docs_dropped counts (v1.20.0), filter snapshot. | |
| name | No | DEPRECATED — use `symbol`. Pre-v1.7 alias, still accepted; emits a deprecated_args notice in _meta. | |
| limit | No | Max results | |
| since | No | Restrict results to files changed between `<rev>..HEAD` (accepts anything `git diff` understands: `main`, `HEAD~3`, `origin/main`, SHA). Mutually exclusive with `since_branched` and `changed_only`. | |
| strict | No | Use scope-resolved (type-aware) references from the binder — drops string-literal/comment/wrong-scope noise. Recommended for refactor work; falls back to legacy refs FST on languages without binder support. | |
| symbol | Yes | Exact symbol name to find references to — canonical key (v1.7+). | |
| exclude | No | Blacklist results by path glob; wins over include (repeatable) | |
| include | No | Whitelist results by path glob, gitignore syntax (repeatable) | |
| workspace | No | Multi-repo: fan out across every repo declared in the nearest `.vex-workspace.toml` (set `project_root` at or above it — the manifest is found by walking up). Results become an object `{workspace, repos:[...]}` grouped by repo, NOT the flat per-tool array — branch on shape. `why` is ignored in workspace mode (single-repo only). | |
| auto_update | No | Auto-update the index if stale, or bootstrap it if missing, before running (default: true) | |
| filter_path | No | Substring path filter applied to result paths (single substring; use include/exclude for glob patterns). Legacy alias: `filter`. | |
| async_update | No | With auto_update, refresh a stale index in the background instead of waiting for it: results come from the index already on disk and _meta.vex.dev/stale says so (default: false) | |
| changed_only | No | Restrict results to working-tree changes (staged + unstaged + untracked). Mutually exclusive with `since` and `since_branched`. | |
| include_docs | No | (non-strict only) Keep matches in `*.md` / `*.markdown` / `*.txt` / `*.rst` / `*.adoc` files. v1.20.0+ strips them by default — README/CHANGELOG mentions of a symbol are prose, not callers. No-op when `strict=true`. | |
| include_self | No | (non-strict only) Keep the row at the symbol's own definition line. v1.20.0+ strips it by default — `find all callers` queries don't want the declaration showing up as a usage. No-op when `strict=true` (the scope-binder excludes the def-site by construction). | |
| project_root | No | Absolute path to the project root (defaults to the MCP working directory) | |
| exclude_tests | No | Drop test files from the results (tests/ dirs, *_test.*, test_*.py, *.spec.ts, __tests__/, tests.rs, ...; same set as tests_for). Composes with include/exclude. Path-based only: Rust unit tests inside a `#[cfg(test)] mod tests` block of a non-test file are not excluded. | |
| no_stale_check | No | Skip the staleness check that runs before each call; assumes the index is fresh. Redundant when `auto_update` is true. | |
| since_branched | No | Restrict results to files changed since this branch diverged from `origin/main` (or `main`/`master`). Mutually exclusive with `since` and `changed_only`. |