Set up vexp, ship faster

Introduction

vexp is a local-first reliability layer for AI coding agents. Its context engine builds a live dependency graph of your codebase and serves your agent only the code that matters for the task; when the agent declares the task done, vexp verifies the work mechanically against that same graph. Session memory persists across days, and an optional local AI layer adds an extra +30 % token savings. Everything runs on your machine.

The VS Code extension is the primary distribution. A standalone CLI (npm install -g vexp-cli) is available for terminal-only workflows. Both bundle the same native engine and MCP server — no external dependencies, no account required. The VS Code extension needs no Node runtime; the npm CLI requires Node 20 or later.

How it works

Installation

Pick a distribution. The VS Code extension is the fastest path; the CLI is for terminal-only setups (Claude Code, Codex, scripts, remote machines).

Platform support

First Run

Pick your distribution below. Both paths end with the same result: a working index, a configured AI agent, and a daemon that auto-restarts when needed, usually within 30 seconds on a typical project.

VS Code Features

Beyond what your AI agent calls via MCP, vexp gives you visible feedback directly in VS Code (works the same in Cursor and Windsurf).

Sidebar panel

Click the vexp icon in the Activity Bar to open a sidebar with:

• Status header (running / indexing / starting / connecting / stopped / error / workspace cap reached / not initialized) and live index stats (nodes, edges, files, uptime, agent sessions).
• Activity (7 days): prompts analyzed, silences, orientations served, and — when active — a Held out (A/B) row for the measurement holdback (disable with holdback_pct = 0 in .vexp/vexp.toml).
• Measured savings (tool calls) section — appears once at least one measured tool call exists — with a period selector (today, 7 / 14 / 30 / 60 / 90 days) and an Export Report button that writes a markdown report to .vexp/token-savings-report.md.
• Local LLM section with Install / Start / Disable / Check-updates / Status buttons, plus a one-time notification that offers to enable it.
• Contextual actions that follow daemon state: while running — Stop Indexing, Force Re-index, Generate Context Capsule, Add / Connect Repository, Setup Agents, Settings, View Daemon Logs; while stopped — Start Indexing, Setup Agents, Activate License, View Daemon Logs.
• Repository cards (status dot with an 'indexing NN%' badge while indexing, repo alias and path, node / edge / file counts, last-indexed time). A toggle shows or hides empty repos.

The panel auto-refreshes every 10 seconds.

CodeLens

Functions, methods, classes, interfaces, enums, and other indexed symbols in TypeScript, JavaScript, Python, Go, Rust, Java, C#, C, C++, Ruby, and Bash get an inline annotation once the file is indexed: first vexp: analyze impact, then N dependents across M files (plus | K cross-repo when cross-repo dependents exist). Click it to open the impact graph for that symbol. Available on every paid plan (Pro, Team, and lifetime tiers); not on the free plan.

Hover

Hover an exported TypeScript/JavaScript declaration (a line containing the export keyword) to see its dependents count, cross-repo usage, and top 5 callers. Available on every paid plan.

Status bar

The left-side status bar shows the current state. Clicking it opens your license status — except in the vexp: not indexed state (click starts indexing) and the vexp: workspace cap state (click opens the logs).

Linked repos in VS Code

The active workspace's .vexp/workspace.json governs how repos are linked. See Multi-Repo Workspaces for the cross-repo features.

Commands

Everything you'll actually type, organized by where you type it.

MCP Tools

Your AI agent uses these tools through MCP. You won't call them directly, your agent does, but it helps to know what each one does.

run_pipeline at a glance

run_pipeline replaces the older multi-step workflow with a single call that picks the right strategy for your task.

For multi-repo workspaces, scope a query with repos: ["backend", "shared"].

Session Memory

vexp remembers what your agent explored, decided, and learned, automatically, across sessions and days. Memories are linked to the code graph, so when the underlying code changes, related memories are flagged stale (your agent sees that the past decision may no longer apply).

How it works

• Auto-capture. Every vexp tool call your agent makes becomes a compact observation in the local database.
• Auto-surface. run_pipeline and get_context_capsule include relevant memories in the result, no extra tool calls needed.
• Each result explains itself. A short rationale tells the agent why this memory surfaced (matching the task, recent activity, related code, etc.).
• Staleness tracking. When code linked to a memory changes, the memory is marked stale and demoted in ranking, but still shown with a warning so the agent can re-evaluate.

The three memory tools

All three are included on every plan, Starter included, and none of them count against the daily quota. Note that on Starter they still stop answering once that quota is spent, because the daemon shuts down until it resets at midnight UTC:

• get_session_context, observations from the current and previous sessions.
• search_memory, cross-session search across everything vexp has captured.
• save_observation, manually record an insight. Optionally link it to a symbol so it gets flagged when that symbol changes. Manually saved observations persist permanently. Auto-captured observations are ephemeral: when a session is compressed they are rolled into a session summary and pruned.

Supported Agents

vexp auto-detects and auto-configures 15 AI coding agents. Running vexp setup writes the correct configuration file for each installed agent, including tool-usage instructions tailored to that agent. For Windsurf and Kiro, setup also pre-approves the vexp tools in the MCP entry (alwaysAllow / autoApprove), so those agents never prompt per call.

Claude Desktop is two surfaces, not one. The desktop app hosts a Claude Code pane, and that pane is Claude Code: it reads ~/.claude.json and the project's .claude/ hooks, so the Claude Code row above already covers it and vexp setup needs nothing extra. Because those hooks inject context into the prompt rather than showing up as tool calls, vexp can be working there without ever appearing in the transcript. The app's plain chat is the other surface: it speaks MCP through claude_desktop_config.json and is not written by vexp setup. A chat with no repository open has nothing to index, so most people never need that entry, add it only if you want vexp in the plain chat pinned to one workspace.

Antigravity note. Antigravity reads the cross-tool AGENTS.md (v1.20.3+) together with GEMINI.md and .agent/rules/, and keeps its MCP servers in a machine-global file: ~/.gemini/antigravity/mcp_config.json. vexp registers its server there once and resolves the workspace per-session, so one configuration serves every project you open.

VS Code forks & Open VSX. The vexp extension also runs in the AI-IDE forks of VS Code, Antigravity, Cursor, Windsurf, Kiro, VSCodium, whose Extensions views are backed by the Open VSX registry (the Microsoft Marketplace is licensed to Microsoft products only). Search for “vexp” there, or use “Install from VSIX” with the same .vsix we ship for VS Code, no fork-specific build needed. Trae ships its own extension store and accepts the VSIX directly.

Windows + WSL2

Inside WSL2, vexp is simply Linux: install the linux-x64 CLI or extension in the WSL side and everything, daemon, index, MCP server, runs there. The one thing to keep straight is that your agents live on both sides of the boundary, and each side reads its own configuration. vexp setup runs inside WSL, so it can only write WSL-side files.

Concretely: the Codex desktop app reads C:\Users\<you>\.codex\config.toml, not the WSL ~/.codex/config.toml that vexp setup writes. Claude Desktop reads %APPDATA%\Claude\claude_desktop_config.json, and the Microsoft Store build relocates it to %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\claude_desktop_config.json.

Bridging a Windows app to vexp in WSL

The entry goes in the Windows-side config and crosses into WSL with wsl.exe. Two rules: environment variables set in the MCP entry do not propagate through wsl.exe (that would need WSLENV), so set them on the command line inside WSL instead; and launch via bash -lc so a version-managed Node (nvm) is on PATH. To find the server path, run npm root -g inside WSL and append /vexp-cli/mcp/mcp-server.cjs.

Cascade reads that one file and no project-level one; quit and reopen Windsurf after editing it. From 3.1.1, vexp setup run inside WSL prints this entry filled in with your real paths, ready to paste. Devin Local (the agent in Devin Desktop) reads .devin/mcp_config.json from the project, which setup writes; if it too runs on the Windows side, the same entry goes in %APPDATA%\devin\mcp_config.json.

With more than one distro installed, pin it: args = ["-d", "Ubuntu", "--", …]. These entries pin one workspace by design, a machine-global config cannot follow whichever project you happen to open, so point VEXP_WORKSPACE at the repo that app should use.

Multi-Repo Workspaces

vexp can index multiple repositories as a unified workspace and detect relationships between them, entirely on your machine. Useful for monorepos split across repos, frontend + backend pairs, and microservices.

Setup

Create .vexp/workspace.json in your primary repo, or click Add / Connect Repository in the sidebar, or run vexp in a terminal and pick Repos & Workspace to list connected repos or add one from the CLI (the plan's repo limit is enforced; a running daemon indexes the new repo automatically).

Paths are relative to the folder that contains the .vexp/ directory: use "." for that root itself, and a subfolder (packages/api) or a sibling (../shared-lib) for every other repo. Listing the root with "." is optional — the primary is always served, and always under its folder name as its alias (an alias you write on the "." entry is ignored). The workspace_id key is also accepted in place of name.

Index the workspace

A workspace is indexed as a whole, not one repo at a time. After creating workspace.json, index every repo in the list in one step, then point your agent's MCP server at the workspace root.

Cross-repo edge detection

vexp automatically detects five kinds of relationship across repos:

Querying across repos

• run_pipeline and get_context_capsule query all indexed repos by default.
• Scope with repos: ["backend"].
• Use cross_repo: true on get_impact_graph and search_logic_flow to trace across repo boundaries.
• Use repo: "alias" on get_skeleton to target a specific repo.
• Call index_status to see available repo aliases.
• From the CLI: vexp capsule --repos backend,shared, vexp impact <fqn> --cross-repo, vexp flow <start> <end> --cross-repo.

Switching workspaces from the CLI

If you have several configured workspaces and use Codex, vexp use <workspacePath> repoints Codex's global MCP config at a different one without re-running setup.

Local LLM (optional)

vexp ships an optional on-device AI layer that improves prompt preprocessing and compression for additional token savings. Everything runs on your machine, no cloud, no account, no code leaving your laptop. Typical extra savings: +30 % tokens on top of the baseline.

Multi-language prose compression: language detection covers 15 languages: English, Italian, French, German, Spanish, Portuguese, Russian, Chinese, Japanese, Korean, Arabic, Hindi, Turkish, Dutch, Polish.

Install & manage

One-time download (~3.5 GB). Files stay on disk after a disable, so re-enabling is instant. Requires at least 6 GB of RAM; below that the installer declines and vexp stays on the built-in rule-based compressor. On NVIDIA Linux/Windows machines, a one-time CUDA plugin (~62 MB) and CUDA 12 runtime (~550 MB) are also downloaded automatically.

GPU acceleration

Works the same in both distributions. On Apple Silicon, Metal is detected and used automatically; Intel Macs run the model on CPU by design. On Linux or Windows with an NVIDIA GPU, CUDA is detected and used automatically, no flag or environment variable is needed. If no usable GPU is found, inference silently falls back to CPU. GPU preference is a config setting: prefer_gpu = false under [llm] in ~/.vexp/config.toml forces CPU inference. flash_attention = "auto" | "on" | "off" (same [llm] table; env default VEXP_FLASH_ATTENTION) — set "off" if your GPU crashes while running the model.

NVIDIA GPUs are supported on Linux and Windows; a one-time CUDA plugin download is fetched automatically. The first GPU inference may take a few seconds to warm up.

GPU offload requires an NVIDIA driver at least as new as CUDA 12.8 (570.xx or newer); on older drivers inference falls back to CPU until the driver is updated. If a GPU attempt ever crashes the daemon, vexp writes ~/.vexp/gpu-unusable and runs the model on CPU from then on. Delete that file after a driver update to retry the GPU (upgrading vexp retries once automatically). If the file says the crash happened while running the model, delete it and set flash_attention = "off" under [llm] to keep the GPU.

Use your own server (optional)

Instead of the ~3.5 GB download, point vexp at any OpenAI-compatible server via endpoint / endpoint_model / endpoint_api_key under [llm] in ~/.vexp/config.toml (llama.cpp llama-server, LM Studio, vLLM, Ollama /v1, AMD Lemonade, FastFlowLM on Ryzen AI NPUs). The endpoint is tried first at daemon start, with automatic fallback to the local model, then the rule-based compressor.

Configuration

vexp works out of the box. Tune it via VS Code settings, .vexp/vexp.toml, environment variables, or ignore files.

VS Code settings

All under the vexp. prefix in Settings or your settings.json:

.vexp/vexp.toml

Optional file at .vexp/vexp.toml inside the repo (all keys top-level — no [index] table). Useful for ranking hints and indexing limits:

In a multi-repo workspace, the primary workspace's .vexp/vexp.toml is the default for every connected repository. A connected repo needs its own file only where it wants to differ, and any key it sets there wins for that repo; keys it leaves out come from the workspace. So raising max_file_size_kb once on the primary applies to all of them. (Before 2.7.1 each repository read only its own file, so a workspace-level setting had no effect on the others.)

A source file over max_file_size_kb is not indexed at all: its symbols and the calls it makes are invisible to impact,search and run_pipeline. Since 3.1 every such skip is recorded in .vexp/coverage.json, flagged by vexp doctor and the index_status tool, printed after vexp index, and disclosed in the header of every pipeline answer. Before 3.1 the only trace was a line in the daemon log.

Environment variables

Manifest & git

.vexp/index.db is local-only (gitignored by default). .vexp/manifest.json contains a small list of content hashes and is committed to git, clones rebuild incrementally from it (typically < 5 s on a 5 000-file repo). The pre-commit hook refreshes the manifest but does not stage it into your commit automatically; opt in with stage_manifest = true in .vexp/vexp.toml. A merge driver auto-resolves manifest conflicts. Git hooks (pre-commit, post-checkout, post-merge) keep the index in sync. Disable any of this with vexp.autoCommitIndex / vexp.gitHooksInstall. Existing hooks coexist via marker-delimited blocks.

Ignore files

vexp honours .gitignore, .vexpignore, and .vexp_ignore, all using gitignore syntax. Common directories are excluded by default: node_modules, .git, .vexp, target, dist, .next, __pycache__, build, vendor, Pods, DerivedData, .expo, venv, .venv, site-packages, .tox, .gradle, .m2, bin/Debug, bin/Release, obj, coverage, .nyc_output, test-results, playwright-report. Nested git checkouts (worktrees, submodules) are pruned as whole subtrees, and minified assets (*.min.js, *.min.css, *.bundle.js, ...) are skipped by filename.

Supported Languages

vexp parses 36 languages plus Markdown, CSS/SCSS/LESS stylesheets included. 32 have a dedicated tree-sitter grammar with language-specific extraction. For Vue, Svelte and Astro the <script> block (and Astro's --- frontmatter) is parsed as TypeScript; for Razor/Blazor the @code/@functions blocks are parsed as C#. Symbols keep their real file line numbers, and every component file gets a component node searchable by name. Templates/markup are not parsed. SQL indexes DDL, tables, views, functions, indexes, triggers from migrations and schema files. Markdown is indexed via a structural heading scan (no tree-sitter).

Markdown indexing

Markdown files (.md, .mdx, .markdown) are first-class index nodes. Each file becomes a Document node (named after the file stem); each ATX heading (# through ######) becomes a nested Section node; each http:// or https:// URL becomes a Link node (URLs inside fenced code blocks are skipped).

Planning documents, spec.md, plan.md, tasks.md, README.md, ADRs under docs/adr/, RFCs under docs/rfcs/, get a ranking boost when an agent searches for design or architecture context. Surfaced through run_pipeline and get_skeleton like code files.

Troubleshooting

Pick your distribution for the distro-specific issues, then check the cross-distro table below for the rest.

Cross-distro issues

These apply whether you use the VS Code extension or the CLI.

Uninstall

A complete removal has two parts: remove the distribution you installed, then (optionally) clean up what vexp wrote on disk. Nothing vexp writes is hidden or system-level, everything lives in your home directory and your project folders.

Leftover data (optional cleanup)

These are safe to delete once vexp is removed. All of them are plain files and directories, no registry entries, no system services.

If you skipped autostart uninstall

Removed the CLI before running vexp autostart uninstall? The login hook is a single per-user file, delete whichever exists:

Privacy & Security

vexp is designed for codebases you can't send to the cloud. Everything runs on your machine.

• Local-only by default. Zero network calls for parsing, indexing, or querying. Outbound calls are limited to: (1) an optional, opportunistic license refresh — opt out with VEXP_OFFLINE=1, which disables all license network calls (vexp keeps a 14-day grace period); (2) an advisory CLI update-availability check against the npm registry — cached 4 hours, never blocks a command, and skippable with VEXP_SKIP_UPDATE_CHECK=1 or --skip-update-check; (3) the explicit, opt-in local-LLM model download when you run vexp setup-llm. Nothing else ever leaves your machine.
• No code execution during indexing. vexp parses your code with tree-sitter; indexing and querying never execute it. The one exception is opt-in and explicit: vexp verify --run-tests (or tests_gate = "run") runs your repo's own test suite, bounded, at your request.
• Telemetry is opt-in. Telemetry is opt-in and off by default. The vexp.telemetry.enabled setting exists for future use; today vexp transmits nothing.
• Distribution integrity. Binaries ship exclusively through npm (with registry integrity checksums) and the VS Code / OpenVSX marketplaces; there is no browser-download channel. macOS binaries carry the Apple toolchain's standard ad-hoc signature and are not Developer-ID notarised today: npm and marketplace installs are never quarantined, so Gatekeeper does not evaluate them. If your security policy requires notarised or countersigned artifacts, contact us about the enterprise distribution line.
• Secret filtering (default on). Files named like credentials are dropped at index time: .env, .env.production, .env.local, id_rsa, *.pem, *.key, secrets.yaml, secret.md, password.json, credentials.toml, and similar filename-boundary matches.
• Template files allowlisted. .env.example, .env.sample, .env.template, .env.test, secrets.example.*, and secrets.sample.* are not excluded, they document contracts, not secrets.
• Filename boundary matching. Legitimate source files that just contain the word secret, password, or credential in their name, e.g. src/secret-manager.ts, are not excluded.
• Custom exclusions. Add patterns to .vexpignore (gitignore syntax; the older .vexp_ignore name is also honored), or set exclude_patterns = ["generated/**", "vendor/**"] at the top level of .vexp/vexp.toml — repo-root-relative globs; a bare pattern like dist/** also matches at any depth. To disable the secret filter entirely, set filter_secrets = false at the top level of .vexp/vexp.toml.

Plans & Quotas

Quotas at a glance. For prices and the upgrade button, see the full pricing on the homepage.

What happens at the limits

• At 80 % of the node cap, the VS Code extension shows a warning (once per session, on any node-capped plan). CLI-only setups get no 80 % warning.
• At 100 % of the node cap, new nodes stop being added. Your existing index keeps working, no data loss.
• At 20 daily calls, the next call to a quota-affected tool returns a limit-reached error and the daemon shuts down. This stops every vexp tool, not just the quota-affected ones, until the quota resets at midnight UTC. Nothing is lost: your index and session memories are kept on disk and are there when it comes back (or upgrade to Pro/Team, whose ceilings interactive use never reaches).

License activation

Offline use

vexp refreshes your license quietly in the background whenever you're online. If you stay offline, you keep working at your current plan for at least 14 days; after that vexp falls back to your license key itself, which keeps the paid plan until its own expiry date. Only when that also lapses does vexp drop to Starter — no data loss, and your plan returns automatically the next time you're online.

Account portal

Manage your subscription, devices, and team at vexp.dev/account (magic-link login). Team owners can add or remove members; each member logs in independently.

Device limit

Each subscription covers a limited number of devices (4 by default). A machine over the cap runs at Starter limits until you free a slot at vexp.dev/account/devices — your key stays valid, and the plan returns automatically on that machine once a slot is free.