vexp VS Code Extension

Introduction

vexp is a local-first context engine that reduces token consumption by 65–70% for any AI coding agent. Instead of passing entire files to the model, vexp analyzes your codebase with tree-sitter, builds an AST dependency graph, and returns only the relevant pivot nodes plus compact skeletons of supporting files.

The VS Code extension is the primary distribution for v1.0. It is fully self-contained: the Rust daemon (vexp-core) and the MCP server (vexp-mcp) are bundled inside the extension package — no external dependencies or manual npm install required.

How it works

Installation

The extension is distributed exclusively through the VS Code Marketplace and runs on VS Code and all VS Code-based editors: Cursor, Windsurf, and any Electron fork that supports the VS Code extension API.

Install from the Extensions panel

Open the Extensions panel (Ctrl+Shift+X / ⌘⇧X), search for vexp, and click Install. The same steps apply in Cursor and Windsurf — both expose the standard VS Code Extensions panel.

Platform support

First Run

The extension activates automatically when you open a workspace containing TypeScript, JavaScript, Python, Go, or Rust files. On first activation it:

1. Selects and verifies the correct native binary for your platform.
2. Starts the vexp-core Rust daemon.
3. Starts the vexp-mcp MCP server on port 7821.
4. Checks for an existing .vexp/index.db in the git root.
5. If the index exists → runs an incremental sync (usually under 5 s).
   If not → runs a full background index (progress bar visible in the status bar).

Workspace setup command

Run the setup command from the Command Palette to configure AI agents automatically. vexp detects which agents are present in your workspace and writes the appropriate config files.

This generates agent-specific configuration files (e.g. .claude/CLAUDE.md, .cursor/rules, .windsurf/rules) that instruct the agent to call get_context_capsule before any code modification.

Status bar

The vexp status bar item is always visible at the bottom of the editor window:

Git hooks

On first run, vexp offers to install lightweight git hooks that keep .vexp/index.db in sync with commits. A VS Code notification lets you approve or decline. The hooks are simple shell scripts — they do not depend on Node or npm.

Configuration

All settings are accessible via File → Preferences → Settings (search for vexp) or directly in your settings.json.

Example settings.json

{
  "vexp.maxContextTokens": 16000,
  "vexp.skeletonDetail": "detailed",
  "vexp.autoCommitIndex": true,
  "vexp.logLevel": "warn"
}

Commands

All commands are available from the Command Palette (Ctrl+Shift+P / ⌘⇧P). Type vexp to filter.

Supported Languages

vexp uses tree-sitter grammars compiled to WASM and bundled directly in the Rust binary — no downloads at runtime.

Supported Agents

When you run vexp: Setup Workspace, the extension scans for known AI agents in your workspace and automatically writes or patches their configuration files to register vexp as an MCP server.

MCP Tools

vexp exposes 7 MCP tools. Your AI agent calls them automatically based on the instructions in the generated config file. You can also call them directly from the Command Palette for debugging.

Git Integration

vexp stores the index in .vexp/index.db at the git root and commits it alongside your source code. This means new team members get a pre-built index when they clone the repository — no waiting for a full re-index.

Directory structure

repo-root/
├── src/
└── .vexp/
    ├── index.db          ← SQLite graph (binary, git-tracked)
    ├── index.db-wal      ← in .gitignore
    ├── index.db-shm      ← in .gitignore
    ├── manifest.json     ← human-readable metadata
    └── .gitattributes    ← marks index.db as binary

Git hooks

vexp installs three lightweight hooks written in shell/Rust (no Node dependency):

Merge conflicts on index.db

index.db is a binary file and cannot be merged line-by-line. vexp installs a custom git merge driver that automatically resolves conflicts:

1. Takes the index.db from the branch with the more recent manifest.json timestamp as the base.
2. Re-indexes only the files modified by the other branch.
3. In the worst case, re-indexes the entire repository in the background — the merge never blocks.

Large repositories and Git LFS

For codebases with more than ~5 000 source files, index.db may exceed 100 MB. vexp automatically detects this and suggests enabling Git LFS for the file:

Opting out of git integration

If you prefer not to commit the index, set vexp.autoCommitIndex and vexp.gitHooksInstall to false in settings, and add .vexp/ to your .gitignore. The extension will still work — each developer simply re-indexes on first open.

Multi-Repo Setup

vexp can index multiple repositories simultaneously and query across their boundaries. This is particularly useful for microservices, monorepos split across multiple git repositories, or frontend + backend pairs.

Setup wizard

Run vexp: Setup Multi-Repo Workspace from the Command Palette. The wizard creates a .vexp/workspace.json and registers each repository.

workspace.json format

{
  "name": "my-project",
  "version": "1",
  "repos": [
    {
      "alias": "frontend",
      "path": "/projects/my-project-frontend",
      "languages": ["typescript"],
      "role": "consumer"
    },
    {
      "alias": "backend",
      "path": "/projects/my-project-backend",
      "languages": ["go"],
      "role": "provider"
    }
  ],
  "cross_repo_links": [
    {
      "type": "openapi",
      "source": "backend:src/api/openapi.yaml",
      "consumer": "frontend:src/api/generated/"
    }
  ]
}

Cross-repo query

Once configured, MCP tools automatically traverse repository boundaries. Pass multiple repo aliases to target specific repositories:

get_context_capsule
  query: "Add the roles field to the user API response"
  repos: ["backend", "frontend"]

VS Code multi-root workspaces

vexp integrates natively with VS Code Multi-root Workspaces (.code-workspace files). When VS Code opens a multi-root workspace, vexp detects all folders, indexes them separately, and activates the cross-repo query engine automatically.

Cross-repo storage

Cross-repo relationship data is stored in ~/.vexp/registry.db — a SQLite database shared across all workspaces on the machine. Per-repo indexes remain in each repository's .vexp/index.db.

Troubleshooting

Extension not activating

vexp activates when the workspace contains supported source files (.ts, .py, .go, .rs, etc.) or an existing .vexp/manifest.json.

• Ensure the workspace folder contains at least one supported source file.
• Check the VS Code Output panel: select vexp from the dropdown.
• Try vexp: Force Re-index from the Command Palette.

Index not updating

• Check the status bar — if it shows indexing…, a full re-index is already running.
• Run vexp: Show Index Status to see the current node count and last indexed commit.
• If the daemon appears stuck, restart it via vexp: Force Re-index.

Port 7821 already in use

Change the MCP server port in settings:

{
  "vexp.mcpPort": 7822
}

Binary permission denied (macOS / Linux)

On first install, the Rust binary may not be executable. The extension sets the correct permissions automatically, but if you see a permission error:

macOS Gatekeeper warning

vexp binaries are signed with an Apple Developer Certificate and notarized. If Gatekeeper blocks the binary, open System Preferences → Privacy & Security and click Allow next to the vexp entry.

Daemon crashes on startup

• Set vexp.logLevel to "debug" and restart VS Code.
• Check the Output panel for vexp daemon logs.
• On Linux: ensure /tmp is writable (the daemon uses a Unix socket there).
• On Windows: ensure the named pipe namespace is accessible (no restrictive AppContainer policy).

AI agent not using vexp tools

• Verify the MCP server is running: vexp: Show Index Status.
• Re-run vexp: Setup Workspace to regenerate the agent config file.
• For Claude Code: ensure the .claude/CLAUDE.md file is in the project root and that Claude Code picks up MCP servers from that file.
• For Cursor/Windsurf: check that the MCP extension is enabled in the editor settings and that the port matches vexp.mcpPort.

Index too large for git

For repositories with more than ~5 000 source files, index.db may exceed 100 MB. vexp will prompt you to enable Git LFS. If you want to opt out of committing the index entirely, see the Git Integration section.

Privacy & Security

.vexp_ignore example

# Exclude secrets and environment files
.env*
*.pem
*.key
secrets/

# Exclude generated code
src/generated/
dist/
build/

# Exclude large data directories
data/
fixtures/large/

Plans & Limits

vexp counts indexed nodes — not lines of code or file count. A node is a distinct symbol: function, class, method, interface, variable, or type alias. As a reference: the vexp codebase itself (~50 source files) generates ~500 nodes.

Starter plan paywall behavior

vexp never blocks you or loses data at the node limit. As you approach the limit:

• At 80% (1,600 nodes) — a non-blocking informational notification appears in the status bar.
• At 100% (2,000 nodes) — new files are still indexed but excess nodes are excluded from queries. Upgrade to Pro for 50,000 nodes and all 7 tools.

License & activation

Licenses are tied to your vexp account (email + device fingerprint). To authenticate: