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 compresses prompts and context further. 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, and the parts that add up to it: silences, orientations served and, when there are any, Held out (A/B) for the measurement holdback (disable with holdback_pct = 0 in .vexp/vexp.toml) and Past hook budget for orientations that finished after the agent stopped waiting.
• 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 detects and configures 17 AI coding agents. Running vexp setup writes the correct configuration file for each agent it sets up, 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. Every vexp tool also declares what it does in MCP terms (read-only, or writing only vexp's own local data), so Codex no longer asks permission before each vexp call and codex exec with approvals set to never no longer refuses them.

Which agents get set up. An agent the project itself shows is set up without asking: its own folder or file in the project (.claude, .cursor, opencode.json, …; for Codex a project .codex/config.toml, never AGENTS.md or anything else vexp writes), or an agent you chose for this project before. A tool found only on this machine (Codex's login, sessions or history under ~/.codex or CODEX_HOME, the ~/.claude folder, Antigravity's ~/.gemini/antigravity, Cline's VS Code storage) is not set up on its own. VS Code asks once per project, one question per tool: Set up / Not here / Never. vexp setup lists such a tool unselected, and without a terminal skips it and prints the command that adds it.

The answers live in ~/.vexp/agent-consent.json (per project, plus a list of tools you never want), shared by the extension and the CLI. Set up, or picking the tool in vexp setup, vexp setup-agents or vexp use, records yes. Not here records no for this project and removes what vexp wrote there for that tool (its AGENTS.md block when no other tool set up here reads it, its .codex hooks), keeping your own text and files. Never says no for every project on this machine, does the same cleanup, and removes vexp's machine-wide entry for that tool (Codex, Antigravity, Cline) when it names no project or this one; ~/.claude.json is never touched. Closing the question answers nothing: it comes back at the next start.

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.

Codex note. vexp's entry in ~/.codex/config.toml names no project: Codex starts vexp in each session's own folder, so every project gets its own index. An entry an earlier release pinned to one project is rewritten this way the next time vexp sets Codex up. In a folder that is not a vexp project, vexp answers with no tools and says why, instead of failing Codex's start. To make every Codex session use one project's index, whatever folder it starts in, run vexp use <path> --pin; vexp use --unpin undoes it.

Codex runs a project hook only after you trust it. When vexp writes or changes its orientation hook, VS Code shows this step once and vexp setup prints it: in the Codex extension for VS Code, open the Codex panel > Settings > Hooks and trust vexp-hint; in a terminal, run codex in the project, type /hooks and approve vexp-hint (trust the folder first if Codex asks). On Windows the hook is registered as cmd /d /c call "<project>\.codex\vexp-hint.cmd", which runs whether Codex starts it through PowerShell or cmd, and the terminal and the VS Code extension keep separate approvals, so approve it in each one you use. After updating from 3.2.5 on Windows, approve it once more: its command changed. vexp doctor shows which approvals are in place.

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. Devin Desktop Next (the beta build) is a separate install with its own copy at %USERPROFILE%\.codeium\windsurf-next\mcp_config.json; the same entry goes there. 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 bridged entries pin one workspace by design, a Windows-side config cannot follow whichever WSL 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 — the alias is the one run_pipeline prints next to each file. The alias is optional: an absolute path pins its repo, and a repo-relative path is looked up in the primary first, then in every connected 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.

Git worktrees and parallel agents

Agent harnesses create a linked git worktree per parallel task (Claude Code under .claude/worktrees/, Cursor's background agents, or your own git worktree add). A worktree is a full copy of the checkout, and it is the same project, and vexp treats it that way everywhere. The generated git hooks detect a linked worktree from .git's own gitdir line — no path convention, so every agent is covered — and skip per-worktree indexing (set VEXP_WORKTREE_INDEX=1 to opt back in); the login supervisor (vexp serve) never resurrects worktree daemons after a reboot and staggers the daemons it does bring back. A new worktree needs no setup of its own: it takes the answer you gave for its repository, so the first agent session in a worktree of a repository set up with vexp indexes it in the background (a worktree of a repository that never had vexp is left alone); until it is complete, answers say they cover only the files indexed so far. On Windows, agents connected through vexp's Node MCP server still need vexp index in a new worktree. That index is kept out of git, so git worktree remove works without --force and takes it along once the session has ended. A daemon started in a worktree shares one license slot with its repository, is not revived at boot, and stops about a minute after the worktree is removed. On Windows a file in use cannot be deleted, so removing a worktree while a vexp daemon runs in it leaves the folder behind; the daemon then stops and the folder can be deleted. To have the index ready before the first prompt, run vexp index from the script your tool runs when it creates a worktree (a Codex local environment's setup script, for example), or set VEXP_WORKTREE_INDEX=1. Submodules are separate projects and are untouched by all of this.

Codex across several workspaces

Nothing to switch: Codex's vexp entry names no project, so each Codex session uses the index of the folder it starts in. To make every Codex session use one workspace instead, run vexp use <workspacePath> --pin; vexp use --unpin undoes it.

Local LLM (optional)

vexp ships an optional on-device AI layer that improves prompt preprocessing and compresses the context further. Everything runs on your machine, no cloud, no account, no code leaving your laptop.

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.

Extension users need none of these commands: the sidebar's Install LLM / Start LLM / Disable LLM buttons drive the bundled binary directly. One thing to know either way: the daemon builds its compressor when it starts, so enabling the model changes nothing until the daemon is restarted — vexp: Restart Daemon from the Command Palette, or vexp daemon-cmd restart. When the sidebar shows "LLM is configured but this daemon is running the rule compressor", that is the case it describes; the banner carries a Restart daemon button and the Start/Install actions offer the restart themselves.

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.

Share one model across environments

The model is a single ~3.5 GB GGUF file, identical on every platform, stored under the OS data directory: ~/.local/share/vexp/models/vexp-devmind-v1/ on Linux (/root/.local/share/… in a container running as root), ~/Library/Application Support/vexp/models/… on macOS, %APPDATA%\vexp\models\… on Windows. Every Dev Container, WSL distro or machine that installs it downloads its own copy unless you share one. Three ways, best first:

One shared volume. Mount a named Docker volume at the default models directory in every container; install once, and in every other container vexp setup-llm --install (or the sidebar's Install LLM) finds the file already there, verifies its size and skips the download — the step only writes that container's config.

Reuse the host's copy. The same mount as a bind mount of the host folder (source=${localEnv:APPDATA}/vexp/models on Windows) needs no second copy at all. The model is memory-mapped, and reading it through Docker Desktop's file sharing is slow: the first calls after a start can exceed timeout_ms, which falls back to the rule compressor for that call. Fine when disk space matters more than warm-up time.

One server, many clients. Serve the GGUF once on the host (llama.cpp llama-server, LM Studio, Ollama) and point every environment at it with endpoint as above — http://host.docker.internal:8080/v1 from a container. No model files anywhere else, and inference runs on the host's GPU, which containers only get with the NVIDIA container toolkit. Any other location works too: model_path under [llm] in ~/.vexp/config.toml names the file directly. The CUDA plugin is per-platform and is not shared.

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.

The file may be UTF-8, with or without a byte-order mark, or UTF-16 as Windows PowerShell and Notepad save it. A file that cannot be read or parsed, or that has a setting of the wrong type, gets one warning in the log naming the file (and the setting); the whole file is then ignored and the defaults apply (in a connected repo, the workspace's settings). vexp still starts.

Delivery boundary

vexp indexes the working tree — shipped code, tests, docs, anything .gitignore does not cover. A project delivered as a package (a WordPress plugin ZIP, an npm tarball) ships a subset, and the file that says which is not .gitignore: it is .distignore (wp dist-archive) or .npmignore. When the repo root has one of those — or delivery_ignore names your own gitignore-syntax file — run_pipeline adds a header line > delivery boundary: .distignore — 2 of 5 pivots are outside the package and tags each such pivot (not shipped), so a file:line citation says whether the code is delivered. Ranking is unchanged; without such a file the output is exactly as before. It is an annotation, not a check of the package contents.

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. 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. Files matching exclude_patterns are out by choice: they are not counted as oversized and never appear in the coverage warning — after adding a pattern, run vexp index once to refresh coverage.json.

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. Existing hooks coexist via marker-delimited blocks.

VS Code asks once per project whether to install them. Skip is remembered for this clone in .vexp/git-hooks.declined (never committed, so a teammate does not inherit it): vexp removes the hooks it had installed and the daemon no longer puts them back. vexp hooks remove, personal mode and the vexp.gitHooksInstall setting turned off record the same answer (the last two withdraw it once you undo them); vexp hooks install reinstalls them and withdraws it. Without the hooks the index still refreshes: the daemon watches the tree while it runs and reconciles it periodically.

Ignore files

vexp honours .gitignore, .ignore, .vexpignore and .vexp_ignore at every level of the tree, plus .git/info/exclude and git's global excludes file, all in gitignore syntax: negations, rules starting with a slash (/chatlogs/) and bare folder names work as in git. The live watcher applies exactly the rules of a full scan, together with exclude_patterns, the size and minified limits and the secret filter, so a file saved while vexp runs is indexed only if a full index would include it. A change to an ignore file in the project or to .git/info/exclude applies within seconds, without a restart, and a file it excludes is removed from the index with its change notes. 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.

Notes kept in the repository. A Markdown file that records the questions you ask vexp is, by construction, the strongest text match for those same questions. Since 3.2.0 a documentation section that records a question (a Q1: label, an expected/got note, a list of questions) is demoted the way CHANGELOG files already are, and files under notes/, journal/, diary/ or scratch/ are treated as records, as are the reports an agent writes when it is done (MISSION_ACCOMPLISHED.md, fixes_summary_final.md); a FAQ that states the question it answers is not touched. Agent instruction files and folders (.claude/, CLAUDE.md, AGENTS.md) rank as repository furniture. The pivot's why line names the rule (quotes the question, diary path). To take a folder out of the index entirely, add it to .vexpignore (/notes/ for a root-anchored rule); an exclude_patterns entry also matches the same name at any depth, so prefer .vexpignore for one specific folder.

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. In Ruby, the methods ActiveRecord generates from has_many, has_and_belongs_to_many, has_one, belongs_to and scope (posts, post_ids, build_author, ...) are indexed as methods of their model since 3.3.1, and so is what delegate defines since 3.3.2. Ruby calls written without parentheses (author.posts, post.author.full_name) are linked through the class the receiver names, its superclasses and the modules it includes; a public_send with a computed name is reported by vexp impact as a dynamic call. Markdown is indexed via a structural heading scan (no tree-sitter). The doc comment directly above a declaration is indexed as the symbol's docstring - JSDoc, Python, Go and Rust since the beginning; Dart ///, C# /// <summary> (XML stripped), Javadoc and Doxygen blocks, Kotlin, Scala, Swift, C, C++, Objective-C, PHP, Ruby, Bash, PowerShell, Lua and OCaml since 3.2.0 - so a plain-English question can match the words of your comments, not only the words inside identifiers. Licence headers, trailing remarks and pragma lines are not docstrings, and secret-shaped values in a comment are masked before they are stored.

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.

A folder with no source code at all is a valid workspace: a knowledge base, a handbook, a tree of ADRs and specs. Run vexp setup in it from the CLI. The VS Code extension activates on a folder that holds source files or an existing .vexp/manifest.json, so in a Markdown-only folder run vexp setup once, or vexp: Setup Agents from the Command Palette, and it picks the index up from there.

What is matched. vexp matches the words of the task against document names, headings and section text, then ranks by structure. There are no embeddings: a question that shares no word with a section does not reach it on its own, which is why it works best through an agent, which turns a loose question into the terms your documents use. Sections come from ATX headings (#); a file with no headings is a single Document node, so the only thing vexp can return for it is the whole file.

What ranks lower. Ranking was tuned on code repositories, where a record of a change is never the answer. Three path rules matter in a knowledge base. A dated file name (2026-09-14-retro.md) and the folders notes/, journal/, diary/, scratch/, blog/, posts/ and releases/ mark a record, which ranks well below a reference document. A folder named exactly like a locale code (fr/, de/, it/, pt-br/) is read as a translation and left out of the answer. If meeting minutes or an it/ department folder are what you need to retrieve, name them otherwise (minutes/vendor-sync-september.md, it-department/).

To see what happened to a document you expected, name it: vexp capsule "who approves a refund?" --explain refunds.md runs the same retrieval and says where that file left it and which rule applied.

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.

Sending a bug report

vexp doctor --report writes .vexp/vexp-report.md: the doctor output as printed, the tool-call ledger of the last 30 days (per tool: calls, median, p95, max, how many ran past 30 s, how many ended with no result, and the ten slowest calls), the warnings and errors from the daemon log with repeats collapsed, and your vexp.toml. It never contains prompt text or file contents — parameters are reported by length only — and secret-shaped values are masked throughout. File paths are visible, so read it once, then send it to staff@vexp.dev or attach it to your issue. The ledger is read straight from the index database, so the report works with the daemon down. --report <file> picks another path.

The report is deliberately mechanical: numbers and log lines, nothing anyone has to second-guess. If you want your agent's observations next to it, paste this prompt into the same session and send the file it produces:

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) a once-a-day license check-in that sends only your license token, an anonymous device id and the vexp version — 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. The VS Code notice and status-bar tooltip, the index_status tool and vexp index say how many source files were left out and the estimated size of the whole project, the two numbers you need to size exclude_patterns or pick a plan. The tooltip and index_status drop it once the index fits under the cap again.
• 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

Daily check-in

Once a day, vexp checks in with vexp.dev from every setup: VS Code, the CLI, or an AI agent running vexp on its own. The check-in sends your license token, an anonymous device id (a random string stored in ~/.vexp/device.id) and the vexp version, nothing else. It registers the machine against your plan's device limit and keeps your license current. Set VEXP_OFFLINE=1 to turn it off; nothing then renews your license key either, so a paid plan lasts until the key's own expiry (30 days after its last renewal) and returns at the next check-in.

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 license covers a limited number of devices: Pro 4, Team 4 per seat, Lifetime Tier 1 and Tier 2 one, Tier 3 five, Tier 4 ten. A machine counts from its first check-in, right away when you activate your key and otherwise within a day. Each environment with its own home folder counts as a device of its own: WSL next to Windows, or a dev container. On a lifetime license, 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. A slot is freed only when you remove a device there.