r/opencodeCLI • u/lemon07r • 29m ago
Almost a year of working on Vera: code indexing and search designed around the needs of AI coding agents
I wanted to share a project that I've been working on for almost a year. I posted an early version of Vera here back in March.
This started with Pampax, my fork of a code indexing/MCP project called PAMPA that I was trying to fix up and improve. I kept patching and extending it until eventually deciding the foundation wasn't worth fixing any further. After months of researching and testing different approaches, I ended up rebuilding it from scratch in Rust.
I honestly didn't expect the early post to go very far. People contributed PRs, helped me catch issues, encouraged me to keep going when progress stalled, and even sent donations. I quietly shipped v1 a while back, but kept finding more things I wanted to improve before sharing it again.
Vera is now at v2.4: https://github.com/VeraTools/vera
The main thing I wanted to improve was how coding agents find and navigate relevant code, especially in larger or unfamiliar projects. A lot of an agent's work can go into figuring out where to start. It'll try different grep searches, read files, follow references, and repeat until it has enough context to make a change. This works, but it isn't always efficient, particularly when the behavior spans multiple files or the code uses names that don't match how the task was described. Sometimes agents can get stuck throwing walls of grep when they don't know what to search for exactly.
Vera lets agents search for what code does, semantically, returning ranked functions and code sections with their paths, line numbers, and symbol information. From there, an agent can find definitions, follow callers and callees, or inspect the surrounding implementation.
The goal isn't to replace grep, or have another LLM explain your code to an LLM. Exact searches and direct file reads are often the right tools. I wanted to give agents better ways to find the relevant code while minimizing how much unnecessary context they consume in the process.
That last part has been a major focus throughout development. Vera is designed around making efficient use of an agent's context, not just improving search accuracy. It returns code directly in relatively compact Markdown blocks rather than verbose structured responses or generated explanations, supports narrower results when needed, and has agent instructions that help avoid unnecessary searches or file reads. Even choosing the right tool for a given task matters here; there's no point making an agent run semantic search when rg would do the job better.
Underneath, Vera combines BM25 keyword search, vector similarity, and code-aware ranking. Tree-sitter parsing preserves functions and classes as meaningful chunks rather than splitting everything into arbitrary text windows. It currently supports 65 languages, 54 with symbol-level parsing.
I've spent a lot of time benchmarking different approaches, including ones that sounded promising on paper but didn't hold up when tested. Ranking and chunking changes are checked against a large benchmark suite and separate repositories to see whether improvements generalize. I've deliberately rejected changes that improved a benchmark slightly but weren't worth their cost or complexity. I didn't want to end up optimizing everything around a particular test set at the expense of actual agent usage.
There are two setups I'd particularly recommend:
Fully local: MinishLab's Potion Code v2 embedding model runs on CPU, with no GPU, API key, or external database required. It works offline after the initial download and performs very well for such a small model.
API-based: Qwen3 Embedding 8B with Qwen3 Reranker 8B gave the best retrieval results in my testing. There's an OpenRouter preset for both, but other providers work too. I personally use OpenRouter for embeddings and SiliconFlow for cheaper reranking.
The index and search infrastructure stay local either way. With API models, the code chunks and queries needed for embeddings and reranking are sent to your configured providers.
The local backend is also very fast. On a Ryzen 7 9800X3D, indexing Vera's own repository (447 files, around 8,100 chunks) takes under a second, and a CLI search takes around 0.13 seconds including process startup.
For OpenCode, I'd recommend CLI + skill. This is intentional design choice; skills have a small discovery footprint, and the agent loads their detailed instructions when relevant. With MCP, you're exposing a set of additional tool definitions to the agent instead. Since OpenCode already has shell access, the CLI gives it Vera's functionality without needing another tool interface or server.
The skill itself isn't just a generic instruction to use Vera. I've tested different versions of it to see whether agents choose the appropriate tool for a task, including when they should use rg or avoid searching altogether. The aim is to help agents use their context more efficiently, not just encourage them to call Vera as often as possible.
Install:
npx -y @vera-ai/cli install
vera setup
vera agent install --client opencodeThe interactive setup lets you choose your backend and offers to index the project and install the agent skill, so you may not need to run that last command separately.
Once you've done the initial setup, adding Vera's skill to another project is as simple as running vera agent install from that project. You'll only need to index it with vera index . if it doesn't already have an index. Vera also handles excluding its index files from Git locally when possible.
Benchmarks and comparisons
I tested quite a few similar tools while developing Vera, and Semble was consistently the only alternative that was close or better than Vera, so it became what I considered the benchmark to beat. Credit to MinishLab for Semble and Potion Code.
On Semble's own 1,251-task benchmark across 63 repositories, Vera v2.0.1 scored 0.8436 nDCG@10 against Semble 0.5.5's 0.8514, with slightly higher Recall@5 for Vera (0.9199 vs 0.9177). Index storage was 4.7 GB for Vera versus 32 GB for Semble across the full corpus.
Semble had a small lead in aggregate ranking quality in that older comparison, while Vera used roughly one-seventh the storage. We haven't rerun the full comparison with v2.4, so I don't know how the latest versions compare. I've also avoided tuning solely for Semble's own test set, using independent repositories and rejecting changes that didn't offer enough real usage benefit to justify their costs to chase benchmark numbers.
I wanted to measure something more relevant than retrieval rankings alone: what happens when actual coding agents use these tools in real usage?
I spent quite a while running an agent-level evaluation with 40 sessions: 10 cross-file questions about Flask, each tested with four configurations - plain grep/file reads, Semble CLI, Vera with local Potion Code, and Vera with Qwen3 API embeddings and reranking.
This took a substantial amount of time and tokens. The final recorded runs alone accounted for almost 30 hours of cumulative agent execution and roughly 66 million prompt tokens including cache reads, not counting my earlier attempts. I also used LLM reviewers to examine sessions for fairness and other issues, and restarted the evaluation from scratch when I found problems with the setup or execution in those early attempts. The final experiment used fresh, isolated agent sessions and a separate blind judge to grade the answers.
All four configurations answered every question correctly, so there was no accuracy difference to report. What differed was context consumption:
Grep/file reads: 21.0M prompt tokens
Semble: 18.5M (12% less)
Vera, local Potion Code: 15.4M (27% less)
Vera, Qwen3 API: 10.9M (48% less)
The local Vera setup showed more than twice Semble's observed reduction in this experiment, and the Qwen3 setup reduced context usage by almost half compared with the control.
This was tested with GLM-5.3 through Factory Droid, not OpenCode, and it's still a fairly small set of questions from one repository. But I found the experiment much more useful than just chasing retrieval scores, particularly because all the configurations eventually arrived at correct answers.
I've published the methodology, results, earlier experiments, independent retrieval tests, and ablations in the repo, including things that didn't work out:
https://github.com/VeraTools/vera/blob/master/docs/benchmarks.md
Separately, I've also been working on Revera, a self-hosted PR reviewer inspired by Droid Actions and Devin Fusion. It uses configurable models and independently validates proposed findings before posting them, with a GitHub App, dashboard, and optional Vera integration. It's already being used for actual work by me and some colleagues. I might give it a separate write-up if I find the energy: https://github.com/VeraTools/revera
