vexp Documentation

Introduction

vexp is a local-first context engine for AI coding agents. It builds a live dependency graph of your codebase, then serves your agent only the code that matters for the task — plus session memory across days and an optional local AI layer for 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 Node runtime, no external dependencies, no account required.

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 / error / stopped) and live index stats (nodes, edges, files, uptime).
• Token Savings dashboard with a period selector (today, 7 / 14 / 30 / 60 / 90 days) and an Export 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 first-run modal that offers to enable it.
• Contextual actions: Force Re-index, Generate Context Capsule, Add Repository, Setup Agents, Settings, View Daemon Logs.
• Repository cards (status dot, file count, last-indexed time). A toggle shows or hides empty repos.

The panel auto-refreshes every 10 seconds.

CodeLens

Exported functions, classes, and types in TypeScript, JavaScript, Python, Go, and Rust get an inline annotation: ◆ N dependents across M files. Click it to open the impact graph for that symbol. Available on the Pro plan.

Hover

Hover any exported symbol in the same languages to see its dependents count, cross-repo usage, and top callers. Pro plan.

Status bar

The left-side status bar shows the current state. Click it to open your license status.

Multi-root workspaces

.code-workspace files are supported. 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 MCP 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.
• Progressive disclosure. Memories are served at three detail levels depending on token budget — headline, standard, or full.

The three memory tools

All three are available on every plan, including Starter:

• 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.

Supported Agents

vexp auto-detects and auto-configures 12 AI coding agents. Running vexp setup writes the correct configuration file for each installed agent, including tool-usage instructions tailored to that agent.

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 Repository in the sidebar.

Cross-repo edge detection

vexp automatically detects three 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.

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 with an optional on-device AI layer that adds smart preprocessing, intent detection, query expansion, session summarisation, re-ranking, and anti-pattern nudging. 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 intent 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.

GPU acceleration

Works the same in both distributions. On Apple Silicon and Intel Macs, Metal is detected and used automatically. On Linux or Windows with an NVIDIA GPU, opt in by setting VEXP_GPU=1 in your environment (or, from the CLI, pass --gpu to vexp index).

Supported CUDA architectures

The CUDA plugin ships a PTX baseline plus pre-compiled SASS for specific GPU families. Any NVIDIA GPU from Volta (2017) onward is supported.

JIT-compiled kernels are cached by the NVIDIA driver in ~/.nv/ComputeCache (Linux) or %LOCALAPPDATA%\NVIDIA\ComputeCache (Windows). After the initial ~10 s compilation, every subsequent inference starts instantly.

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 the project root. Useful for ranking hints and indexing limits:

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). 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 the legacy .vexp_ignore), and .ignore (ripgrep convention) — all using gitignore syntax. Common directories are excluded by default: node_modules, .git, target, dist, .next, __pycache__, build, vendor, Pods, DerivedData, .expo.

Supported Languages

vexp parses 30 programming languages plus Markdown. Each has a dedicated tree-sitter grammar with language-specific extraction.

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.

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. The only outbound call is an optional, opportunistic license refresh — opt out by going offline (vexp keeps a 14-day grace period).
• No code execution. vexp parses your code with tree-sitter; it never runs it.
• Telemetry is opt-in. Off by default. When enabled (vexp.telemetry.enabled = true), vexp sends anonymous usage counters only — never code content, filenames, paths, or identifiers.
• Signed binaries. macOS builds are signed and notarised; Windows builds use Authenticode EV signing; all platforms ship with checksums verified at startup.
• 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 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). To disable the secret filter entirely, set filter_secrets = false under [index] in .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 (Starter), you get a one-off 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 status bar turns red and the three quota-affected tools pause until midnight UTC. Every other tool keeps working.

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 up to 14 days. After that vexp falls back to Starter — no data loss, and your previous 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.