Docs · Install Guide · Features · Query Guide · Benchmarks · How It Works · Models · Supported Languages
Local, symbol-aware code search for developers and AI agents.
Hybrid BM25 + vector search with optional reranking, 65 languages, one static binary. Indexes stay on your machine; results come back as symbol-bounded chunks with file paths, line ranges, and scores.
Vector Enhanced Reranking Agent
1. Install
bunx @vera-ai/cli install # or: npx -y @vera-ai/cli install / uvx vera-ai install2. Set up and index
Zero-setup local (CPU, no key, no GPU):
vera setup --potion-code --index .Best measured search quality (one OpenRouter key, Qwen preset):
vera setup --api --index .GPU and other backends
vera setup # Interactive wizard, indexes this project by default
vera setup --onnx-jina-coreml --index . # Apple Silicon (M1/M2/M3/M4)
vera setup --onnx-jina-cuda --index . # NVIDIA GPU
vera setup --onnx-jina-rocm --index . # AMD GPU (ROCm, Linux)
vera setup --onnx-jina-openvino --index . # Intel GPU (OpenVINO, Linux)
vera setup --onnx-jina-directml --index . # DirectX 12 GPU (Windows)The wizard also offers presets for OpenAI, Jina, and Voyage. The Qwen preset uses qwen/qwen3-embedding-8b + qwen/qwen3-reranker-8b via https://openrouter.ai/api/v1 with a single shared key and the generic reranker protocol.
3. Search
vera search "authentication logic"If the current project has no index, interactive search offers to create one. JSON and non-interactive searches still return the missing-index error.
4. Keep .vera/ out of git
echo '.vera/' >> .gitignoreThe index can be large and is machine-local.
See What's New for release notes.
| Token-efficient for agents | Returns symbol-bounded chunks, not entire files. 75-95% fewer tokens on typical queries. In a blind-graded agent benchmark, a mid-tier model with Vera reached the same answer quality while consuming 27-48% less context (48% with the Qwen API embedding+reranker pair, 27% with local Potion defaults). |
| Single binary, 65 languages | One static binary with 61 tree-sitter grammars compiled in. No Python, no language servers, no per-language toolchains. |
| Fast at query time, tiny on disk | 6.4 ms median query latency on the 1,251-task suite (local Potion Code defaults) with a 4.7 GB index for 63 repositories (6.8x smaller than Semble's 32 GB). |
| Updates, not just re-indexes | Incremental updates and watch mode keep the index current as files change. Persistent indexes survive restarts and are reused when identity checks pass. |
| Built-in code intelligence | Call graph analysis, reference finding, dead code detection, and project overview, all from the same index. |
| Holds up off the benchmark | Leads Semble on the independent contamination set (10 fresh repositories, locally generated ground truth) and on recall@5, while trailing by 0.008 nDCG on Semble's own 63-repo benchmark. Details in Benchmarks. |
Vera started as a fork of Pampax. When the design stopped fitting what I wanted from a code search tool, I rebuilt it from the ground up, with each choice backed by research, benchmarking, and the ADRs in this repo. The full feature list covers everything Vera can do.
Vera itself is always local: the index lives in .vera/ per project, config and models in the Vera data directory (see Installation). The backend choice only affects where embeddings and reranking run.
API mode works with any OpenAI-compatible endpoint and needs no local compute. The models guide and installation guide cover provider options, setup flags, Docker, and building from source.
- Linux x86_64/aarch64 (glibc or musl), macOS x86_64/arm64, or Windows x86_64.
- No runtime dependencies; Python and Node are only needed to run the installer wrappers.
- The default local Potion model runs on CPU.
.vera/size scales with the repository; the 63-repository benchmark used 4.7 GB.
Local modes send nothing off-machine. API mode sends chunk text and queries to the configured endpoint. The update check contacts GitHub once a day and is disabled with VERA_NO_UPDATE_CHECK=1.
| ripgrep | Language server | Hosted code search | Vera | |
|---|---|---|---|---|
| Find code by describing what it does | No | No | Yes | Yes |
| Exact text and regex | Yes | No | Yes | Yes (vera grep) |
| Callers, references, dead code | No | Yes, per language | Yes | Yes, 65 languages from one index |
| Works offline, nothing uploaded | Yes | Yes | No | Yes (local backends) |
| Setup | None | One server per language | Account and indexing service | One binary, one command |
| Built for agents (MCP, token-bounded output) | No | Partial | Varies | Yes |
Vera complements ripgrep rather than replacing it: use rg when you know the exact string, Vera when you know what the code does but not what it is called.
vera agent install installs the Vera skill for supported coding agents and can add a short usage snippet to your project's AGENTS.md, CLAUDE.md, COPILOT.md, or editor rules file.
vera agent install
vera agent install --client allClaude Code:
claude mcp add vera -- vera mcpCursor, Windsurf, and generic MCP clients:
{"mcpServers":{"vera":{"command":"vera","args":["mcp"]}}}Codex:
[mcp_servers.vera]
command = "vera"
args = ["mcp"]Vera exposes search_code, get_stats, get_overview, regex_search, structural_search, find_references, and explain_path. See MCP integration for client-specific setup and tool details.
If you use the skills CLI, you can install Vera there too:
npx skills add VeraTools/Veravera search "authentication logic"
vera update .vera search "error handling" --lang rust
vera search "routes" --path "src/**/*.ts" --path "tests/**/*.ts"
vera search "handler" --type function --limit 5
vera search "OAuth token refresh" "JWT expiry handling" "auth middleware"
vera search "config" --intent "find where database connection strings are loaded"
vera search "config loading" --deep
vera search "auth" --compact
vera search "token validation" --changed
vera search "config loading" --base origin/main
vera structural definitions parse_config
vera structural env DATABASE_URL
vera structural routes --path "src/**/*.ts"
vera structural impls Loader
vera references parse_config --changedRepeat --path to match any of several file path patterns. Path patterns use OR semantics; other filters still combine with AND semantics.
| Task | Command |
|---|---|
| Regex or exact text | vera grep "fn\s+main" |
| Common structural tasks | vera structural routes / vera structural env DATABASE_URL / vera structural impls Loader |
| Explain why a file is missing from the index | vera explain-path path/to/file |
| Inspect index health | vera stats --json |
| Find callers | vera references foo |
| Find callees | vera references foo --callees |
| Find dead code | vera dead-code |
| Get a project overview | vera overview |
| Scope a search to changed files | vera search "query" --changed |
| Keep the index fresh | vera watch . |
| Run local HTTP inference server | vera serve |
| Check your setup | vera doctor |
| Repair missing local assets | vera repair |
| Install agent skills | vera agent install |
See the query guide for search tips, the feature list for the full command surface, and vera --help for CLI details.
Defaults to markdown codeblocks (the most token-efficient format for AI agents):
```src/auth/login.rs:42-68 function:authenticate
pub fn authenticate(credentials: &Credentials) -> Result<Token> { ... }
```
Use --json for compact JSON. --raw works with vera search, vera grep, and vera references; --timing works with vera search and vera grep. You can place them before or after the subcommand (for example, vera --timing search "auth" or vera references parse_config --raw).
Vera respects .gitignore by default. Create a .veraignore file (gitignore syntax) for more control, or use --exclude flags. Details: docs/features.md.
If a file is missing from the index and you need the exact reason, run:
vera explain-path path/to/fileSemble benchmark comparison on 1,251 tasks across 63 repositories (Vera v1.4.0 row measured 2026-09-03 on AMD Ryzen 7 9800X3D; Semble column from the 2026-08-23 comparison on the same task set and embeddings):
| Tool | nDCG@10 | R@1 | R@5 | R@10 | MRR | Query p50 | Index time | Index size |
|---|---|---|---|---|---|---|---|---|
| Vera | 0.8437 | 0.6713 | 0.9189 | 0.9502 | 0.8258 | 6.4 ms | 115 s | 4.7 GB |
| Semble 0.5.5, full rerank stack | 0.8514 | 0.6747 | 0.9177 | 0.9656 | 0.8348 | 2.3 ms | 100 s | 32 GB |
Both tools used the same minishlab/potion-code-16M-v2 embeddings, harness, graded relevance, and suffix-corrected path matching in the scorer.
The full-suite gap is on Semble's own development corpus. On the 320-task tuning subset and the independent 10-repository contamination set, Vera leads (0.8538 vs 0.8494, 0.7674 vs 0.7655); Recall@5 favors Vera on the full suite. See full benchmark results.
The agent-context numbers in What Sets Vera Apart come from a blind-graded four-arm agent benchmark; methodology and per-arm results are in Benchmarks.
Vera is at v1.x: the CLI, output formats, and MCP tool surface are stable, and changes are listed in What's New. Bug reports and feature requests go to Issues.
See CONTRIBUTING.md.