Install Guide · Features · Query Guide · Benchmarks · How It Works · Models · Supported Languages
Vector Enhanced Reranking Agent
Code search that combines BM25 keyword matching, vector similarity, and cross-encoder reranking. Supports 65 languages (61 with tree-sitter parsing), runs locally, returns structured results with file paths, line ranges, symbol metadata, and relevance scores.
Vera 1.0 is the first stable release. It ships measured search-quality gains on the full 1,251-task Semble suite, an agent-level benchmark showing fewer input tokens at equal answer quality, repeatable --path filters, vera agent install, the vera serve HTTP server, local-mode hardening, and a set of community-reported fixes. See What's new in v1.0 for details.
1. Install
bunx @vera-ai/cli install # or: npx -y @vera-ai/cli install / uvx vera-ai install2. Set up models (pick one)
vera setup # Interactive wizard (auto-detects your hardware)
vera setup --potion-code # CPU-only local mode
vera setup --api # Remote API mode, prompts for endpoint + key
vera setup --onnx-jina-coreml # Apple Silicon (M1/M2/M3/M4)
vera setup --onnx-jina-cuda # NVIDIA GPU
vera setup --onnx-jina-rocm # AMD GPU (ROCm, Linux)
vera setup --onnx-jina-openvino # Intel GPU (OpenVINO, Linux)
vera setup --onnx-jina-directml # DirectX 12 GPU (Windows)3. Index and search
vera index .
vera search "authentication logic"| Cross-encoder reranking | Most tools stop at retrieval. Vera scores query-candidate pairs jointly, lifting MRR@10 from 0.28 to 0.60. |
| Single binary, 65 languages | One static binary with 61 tree-sitter grammars compiled in. No Python, no language servers, no per-language toolchains. |
| Built-in code intelligence | Call graph analysis, reference finding, dead code detection, and project overview, all from the same index. |
| Token-efficient for agents | Returns symbol-bounded chunks, not entire files. 75-95% fewer tokens on typical queries. |
Vera started after weeks of working on Pampax, a project I forked because it and other similar tools were missing what I wanted. I kept running into deep-rooted bugs, less-than-ideal design decisions, and thought I could build something better from the ground up. Every design choice comes from careful research, learning from other projects, benchmarking and evaluation. Take a look at the full feature list to see everything Vera can do.
Use the quick start above if you just want to get going. This section helps you pick the right backend.
bunx @vera-ai/cli install # or: npx -y @vera-ai/cli install / uvx vera-ai installVera itself is always local: the index lives in .vera/ per project, config and models in $XDG_DATA_HOME/vera (or ~/.vera for existing installs). The backend choice only affects where embeddings and reranking run.
| You have | Run this | What happens |
|---|---|---|
| Not sure | vera setup |
Interactive wizard auto-detects your hardware |
| CPU only | vera setup --potion-code |
Downloads Potion Code static embeddings. No ONNX Runtime needed |
| Remote models | vera setup --api |
Prompts for an OpenAI-compatible endpoint and key |
| Apple Silicon (M1/M2/M3/M4) | vera setup --onnx-jina-coreml |
Downloads local models, uses CoreML GPU acceleration |
| NVIDIA GPU | vera setup --onnx-jina-cuda |
Downloads local models, uses CUDA. Fastest local option |
| AMD GPU (Linux) | vera setup --onnx-jina-rocm |
Downloads local models, uses ROCm |
| Intel GPU (Linux) | vera setup --onnx-jina-openvino |
Downloads local models, uses OpenVINO |
| DirectX 12 GPU (Windows) | vera setup --onnx-jina-directml |
Downloads local models, uses DirectML |
API mode works with any OpenAI-compatible endpoint and needs no local compute. Use vera setup --api --yes with EMBEDDING_MODEL_* variables for non-interactive setup. Potion Code is the CPU-first local backend. Jina ONNX is the GPU local backend and includes the local reranker. After the first index, vera update . only re-embeds changed files, so incremental updates are fast on any backend. Full details: docs/models.md.
For step-by-step instructions, API provider options, Docker, building from source, and troubleshooting, see the full Installation Guide.
MCP server
vera mcp # or: bunx @vera-ai/cli mcp / uvx vera-ai mcpExposes search_code, get_stats, get_overview, regex_search, structural_search, find_references, and explain_path. search_code, structural_search, and find_references auto-index and start a file watcher on first use if no index exists.
The MCP surface stays intentionally small; use the CLI skill path when you need the full command set.
vera index .
vera 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/filev1.0.0-rc full-pipeline benchmark: nDCG@10 0.7327 on the full 1,251-task Semble suite (63 repos). See docs/benchmarks.md for ablation detail.
21-task benchmark across ripgrep, flask, fastify, and turborepo:
| Metric | ripgrep | cocoindex | ColGREP (149M) | Vera |
|---|---|---|---|---|
| Recall@5 | 0.28 | 0.37 | 0.67 | 0.78 |
| MRR@10 | 0.26 | 0.35 | 0.62 | 0.91 |
| nDCG@10 | 0.29 | 0.52 | 0.56 | 0.84 |
Full methodology and version history: docs/benchmarks.md.
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 allIf you use the skills CLI, you can install Vera there too:
npx skills add lemon07r/VeraIf you skipped the prompt and want to add the instructions manually, use the snippet in the Installation Guide.
See CONTRIBUTING.md.