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)

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

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

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

claude mcp add vera -- vera mcp      # Claude Code

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

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

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

Excluding Files

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/file

Benchmarks

Semble 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):

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 Benchmark history.

Status and Community

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.

Contributing

See CONTRIBUTING.md.