modules
Identify code clusters of symbols that call or reference each other. List all clusters or find which cluster a symbol belongs to.
Instructions
De-facto modules: clusters of symbols that call/reference each other (deterministic Leiden-CPM over call + ref + hierarchy edges, computed on full vex index). Without symbol: list clusters with a label (dominant path prefix; a bare file path when the cluster is a single file), size, cohesion and hub symbols. With symbol: that symbol's cluster and its members (limit caps the matching symbols). Use for what are the modules / which module is X in instead of reading directory listings. Requires a v9 index built by vex index; after vex update clusters are frozen and flagged stale. Returns an empty result with empty_reason and a hint on older indexes or when built with --no-clusters. Cluster ids are stable only within one full-index generation: do not persist them across vex index runs.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Order clusters by in-scope size or by cohesion; ties by cluster id. | size |
| limit | No | Max clusters to list, or max matching symbols when `symbol` is given (per repo with `workspace`). Must be at least 1. | |
| symbol | No | Symbol whose cluster to show. Omit to list all clusters. | |
| exclude | No | Blacklist members by path glob; wins over include (repeatable) | |
| include | No | Whitelist members by path glob, gitignore syntax (repeatable). A cluster is shown iff at least one member is in scope. | |
| members | No | Members to list per cluster, ordered by path then line (default: 0 when listing, 25 for a `symbol` lookup). Must be in `[0, 10000]`. | |
| min_size | No | Hide clusters with fewer in-scope symbols than this. List mode only; ignored when `symbol` is given. Must be in `[1, 1000000]`. | |
| 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) | |
| 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) | |
| 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. |