Vera

Local code search for AI coding agents and the developers who use them.

Install · Features · Query guide · Benchmarks · How it works · All docs

Vector Enhanced Reranking Agent

Describe what the code does, and Vera finds it. Ask for "where expired sessions are cleaned up" and you get back the functions and classes that do it, ranked, with file paths and line ranges. Exact names work too.

Vera is a single native binary. The index lives in your project, search runs on your machine, and the default model runs on any CPU with no GPU, API key, or server to manage.

Quick start

# 1. Install (pick one: bunx, npx, or uvx)
bunx @vera-ai/cli install        # or: npx -y @vera-ai/cli install / uvx vera-ai install

# 2. Download the default local model and index the current project
vera setup --potion-code --index .

# 3. Search
vera search "where expired sessions are cleaned up"

Run vera setup with no flags in a terminal for a guided setup that can also install the agent skill. Add .vera/ to your .gitignore. The installation guide covers GPU backends, API mode, prebuilt binaries, and Docker.

What Vera does well

It finds code by behavior and by name. Every query runs keyword search (BM25) and embedding search side by side, merges the two lists, then applies code-aware ranking that prefers definitions over passing mentions and source files over tests and docs. Searching parse_config finds that function; searching "load settings from environment variables" finds it too.

Results are whole functions, not line fragments. Vera parses files with tree-sitter and indexes functions, classes, methods, structs, and other symbols as separate chunks. 54 of the 65 supported languages get symbol-level chunks; config files, docs, and the rest are split by section, whole file, or line windows. An agent reads the relevant symbol instead of opening the whole file.

It is fast on an ordinary CPU. On a desktop CPU (Ryzen 7 9800X3D), Vera indexes its own repository (438 files, about 7,900 chunks) in under a second, and a search from the command line returns in about 0.13 seconds, process startup included. vera update . and vera watch . re-index only the files that changed.

Its search quality holds up against the best local tools. On Semble's 1,251-task code search benchmark, run with the same embedding model, Vera scores within 1% of Semble on nDCG@10 and slightly ahead on Recall@5, with an index about a seventh the size. Details are below.

It does more than search. The same index answers structural questions: where a symbol is defined, who calls it, which routes or environment variables exist, which types implement an interface, and which functions have no callers. You can scope any search to files changed in your working tree or branch.

It is built for agents. vera agent install adds a Vera skill to more than 30 agent clients, including Claude Code, Codex, Cursor, OpenCode, Gemini CLI, and Copilot. Results come back as compact Markdown code blocks with paths and line ranges, which agents read well. An MCP server is included for clients that prefer it.

Using it with an AI agent

The recommended setup is the CLI plus the Vera skill. The skill tells the agent when to reach for vera search, vera references, or plain grep, and how to write queries that work.

vera agent install                  # interactive: pick agents and global or project scope
vera agent install --client all     # every supported agent, global scope

The interactive installer can also add a short Vera section to your project's AGENTS.md, CLAUDE.md, or editor rules file. If you use the skills CLI, npx skills add VeraTools/Vera works too.

vera mcp runs an MCP server over stdio with seven tools: search_code, get_overview, regex_search, structural_search, find_references, explain_path, and get_stats. It indexes the project on first use and keeps the index current while it runs.

claude mcp add vera -- vera mcp                               # Claude Code

{"mcpServers": {"vera": {"command": "vera", "args": ["mcp"]}}}

Setup for Codex, VS Code, and other clients is in the MCP guide.

Common commands

Results come back as Markdown code blocks, one per result, labeled with the path, line range, and symbol. Here is a search over the Flask repository with --compact, which keeps signatures and drops bodies:

$ vera search "load config from environment variables" --compact --limit 2
```src/flask/config.py:50-247 class:Config (part 1)
class Config(dict):  # type: ignore[type-arg] ...
```

```src/flask/cli.py:698-763 function:load_dotenv
def load_dotenv(
    path: str | os.PathLike[str] | None = None, load_defaults: bool = True
) -> bool: ...
```

Without --compact you get the full code of each result. Use --json for machine-readable output. The query guide explains how to write queries that land, and the feature guide covers every command.

Choosing a model backend

Indexing, storage, and search always run locally. The backend only decides where the embedding model runs.

See models and backends for measurements and setup details.

Privacy

With a local backend, your code and queries stay on your machine; only the first model download needs the network. Code or queries go elsewhere only to endpoints you configure: API mode sends chunk text and queries to the embedding endpoint, an API reranker receives queries and candidate chunks (even with a local backend), and --deep with a completion endpoint sends the query to it. Vera checks GitHub for a new release once a day; set VERA_NO_UPDATE_CHECK=1 to turn that off.

Benchmarks

The main benchmark is Semble's task set: 1,251 code search queries across 63 open-source repositories, each with known correct answers. Semble is a popular local code search tool from MinishLab, the team behind the Potion embedding model. Both tools below used that same potion-code-16M-v2 model and the same tasks and nDCG@10 formula; see the benchmark page for how answers were matched.

Vera also scored slightly higher than Semble on the 320-task tuning subset (0.854 vs 0.849) and on an independent set of 180 tasks from 10 repositories outside Semble's benchmark (0.767 vs 0.766). That second set exists to check that neither tool, nor the shared embedding model, was tuned to Semble's own tasks.

In a small agent experiment (10 code-tracing questions about Flask, each answered by a fresh coding agent), every setup answered every question correctly. Agents with Vera used 27% less context than agents limited to grep and file reads, and 48% less with the Qwen API backend; agents with Semble used 12% less. With only 10 questions, the 48% result is the only one that is statistically significant.

Methodology, hardware, latency numbers, and the full history are on the benchmarks page.

How it works

query ─┬─ BM25 keyword search (Tantivy) ─┐
       └─ vector search (embeddings) ────┴─ rank fusion ─ optional reranker ─ code-aware ranking ─ results

Files are parsed with tree-sitter into symbol-sized chunks. Each chunk is indexed twice: as text for keyword search and as an embedding for semantic search. Everything is stored in .vera/ inside your project (SQLite, a Tantivy index, and a flat vector file), so there is no database or background service to run. How Vera works has the details, and the architecture decisions record why each piece was chosen.

Background

Before Vera, I maintained Pampax, my fork of an existing code search tool called PAMPA. I fixed and improved a lot of it, but kept running into limits in its foundation, so I started over. Vera is written from scratch in Rust, and its design choices (storage, chunking, ranking, default model) were each picked by measuring the alternatives. The experiments that did not pan out are documented alongside the ones that did.

Community and support

• Questions, bug reports, and feature requests: GitHub Issues
• Chat and help: Discord
• Release notes: What's new. Upgrading from 1.x: v2 migration
• Contributing: CONTRIBUTING.md

Vera is MIT licensed.