Vera
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
Quick Start
1. Install
bunx @vera-ai/cli install # or: npx -y @vera-ai/cli install / uvx vera-ai install
2. 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 .
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/' >> .gitignore
The index can be large and is machine-local.
See What's New for release notes.
What Sets Vera Apart
| Token-efficient for agents | Returns symbol-bounded chunks, not entire files. 75-95% fewer tokens on typical queries. In a blind-graded four-arm agent benchmark (GLM-5.3, high effort, 10 cross-file questions, one repository), the Qwen embedding+reranker pair consumed 48% less prompt context than a no-tool control at equal 10/10 answer quality, the only per-arm figure statistically significant at that sample size; the local Potion default consumed 27% less on the same lane, within run-to-run noise at N=10. Method and per-arm data: Benchmark history. |
| 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.
Choosing a Backend
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.
Requirements
- 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.
Privacy
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.
Vera vs. Other Tools
| 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 (CLI, skill, MCP) | 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.
Use with AI Agents
The preferred agent integration is the CLI plus the Vera skill: vera agent install installs it 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 all
If you use the skills CLI, you can install Vera there too:
npx skills add VeraTools/Vera
Vera also ships an MCP server: vera mcp. Setup for each client and the full tool list: MCP integration.
claude mcp add vera -- vera mcp # Claude Code
Cursor, Windsurf, and generic MCP clients:
{"mcpServers":{"vera":{"command":"vera","args":["mcp"]}}}
Vera exposes search_code, get_stats, get_overview, regex_search, structural_search, find_references, and explain_path. Client-specific setup and tool details: MCP integration.
Usage
Core Workflow
vera search "authentication logic"
vera update .
Search Patterns
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 --changed
Repeat --path to match any of several file path patterns. Path patterns use OR semantics; other filters still combine with AND semantics.
Common Tasks
| 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.
Output
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.