# vexp-cli — Context Engine for AI Coding Agents (Claude Code, Cursor, Codex)

**Give your AI coding agent the right context, then verify its work — 100% on your machine.**

`vexp-cli` is a local-first [MCP server](https://modelcontextprotocol.io) that pre-indexes your codebase into a dependency graph and feeds any AI coding agent only the code that matters for the task — cutting **87% of the tokens** it would otherwise waste reading whole files. New in 2.5: it also checks the agent's work mechanically when it says it's done, and scans your code for PII and secrets before any model reads them. Your source never leaves your laptop.

```bash
npm install -g vexp-cli
vexp setup      # auto-configures Claude Code, Cursor, Codex, and 14 agents
vexp index      # builds the local graph — no login, no API key
```

[![npm version](https://img.shields.io/npm/v/vexp-cli?color=CB3837)](https://www.npmjs.com/package/vexp-cli)
[![downloads](https://img.shields.io/npm/dm/vexp-cli?color=CB3837)](https://www.npmjs.com/package/vexp-cli)
![local-first](https://img.shields.io/badge/code-never%20leaves%20your%20machine-brightgreen)

---

## Why developers install vexp

Your AI agent burns most of its budget exploring your repo before writing a line of code. It reads entire files, floods its context window, and still misses the one function that mattered. vexp fixes the input **and** the output:

- **📉 The whole session costs less (new in 3.0).** Tuned on full agent sessions against the same agent without vexp, on tasks the tuning never saw: **more tasks resolved (24/25 vs 22/25), 13% less context replay, 8% lower session cost — 20% lower on long sessions.** The turn-zero orientation now carries up to 3× more evidence, and everything that could add a turn to your session is opt-in (`vexp setup --interventions`): by default vexp only subtracts.
- **⚡ 87% fewer tokens per call.** vexp returns ranked pivot files with exact line ranges and blast radius — not whole files. Measured on real usage, not a synthetic benchmark.
- **🔍 Verifies the work (new in 2.5).** When your agent declares a task done, `verify_done` reports what's provably broken or missing — broken imports, parse errors, dependents never updated — each with file and line. No model grades anything; it's git + tree-sitter + the code graph.
- **🛡️ Shield scan (new in 2.5).** `vexp shield scan` shows the emails, API keys, tokens and private keys sitting in your comments and strings that every AI agent currently reads. Local, deterministic, masked.
- **🔒 100% local.** Zero network calls, zero cloud indexing, no account, no API key. Your code stays yours.
- **🤝 Works with everything.** One `vexp setup` configures Claude Code, Cursor, Windsurf, GitHub Copilot, OpenAI Codex, Zed, Cline, Aider, opencode, and more — 14 agents in total.

## How it works

vexp parses **34 languages** with tree-sitter into a local SQLite dependency graph, then serves your agent through the Model Context Protocol:

- `run_pipeline` — ranked pivot files + line ranges + blast radius, in one call
- `get_skeleton` — file structure at 70-90% token savings
- `verify_done` — mechanical completion check
- `expand_vexp_ref` — full symbol bodies on demand

You never call these yourself — `vexp setup` writes the agent config, and your agent calls them automatically. You don't even mention vexp in your prompts.

## Quickstart

```bash
# 1. Install
npm install -g vexp-cli

# 2. Configure your agents (auto-detected) + build the graph
cd your-project
vexp setup
vexp index

# 3. Use your agent normally. That's it.
#    Check savings any time:
vexp savings

# 4. See what your code exposes to AI:
vexp shield scan

# 5. Diagnose anything:
vexp doctor
```

## Supported agents

Claude Code · Cursor · Windsurf · GitHub Copilot · OpenAI Codex · Zed · Continue.dev · Cline · Aider · Kiro · Kilo Code · opencode · Augment · Antigravity · ZCode · Friday Code

## Supported languages

TypeScript, JavaScript, Python, Rust, Go, Java, Kotlin, Scala, C, C++, C#, Ruby, PHP, Swift, Objective-C, Lua, Dart, Elixir, Clojure, Haskell, OCaml, F#, Zig, Bash, SQL, and more — 34 in total.

## Links

- 🌐 Website & docs → [vexp.dev](https://vexp.dev)
- 🧩 VS Code / Cursor extension → [Marketplace](https://marketplace.visualstudio.com/items?itemName=vexp.vexp-vscode) · [Open VSX](https://open-vsx.org/extension/vexp/vexp-vscode)

---

**Keywords:** ai context engine · mcp server · claude code context · cursor context · save tokens · reduce ai coding cost · code context · dependency graph · tree-sitter · local-first · token optimization · ai coding assistant · code intelligence · model context protocol