VeraTools Vera
Ranked code search over an indexed repository. Results are markdown codeblocks: path:line_start-line_end symbol_type:symbol_name, then the code.
Pick the tool
| You are about to... | Do this instead |
|---|---|
| Read files to find where something lives | vera search "config object construction" |
| Read files to understand how something works | vera search "env file loading decision" |
| Find documentation on a topic | vera search "deploying behind proxy" --scope docs |
| Find every occurrence of a pattern | vera grep "TODO|FIXME" |
| Find callers or callees of a symbol | vera references make_config |
| Find definitions, routes, env reads | vera structural env / vera structural routes |
| Edit the same pattern in many files | rg |
| Read a file you already know | Read it directly |
Do not use Vera when
- You already know the exact path and line: open the file.
- You are editing across many files mechanically: use
rg. - The answer is a literal string you can match:
vera grepbeatsvera search. - You have already run two searches that returned the same region: stop searching and read the code.
Search well
- Search behavior, not nouns:
"JWT expiry handling", not"auth"or"utils". - Pass several angles in one call:
vera search "OAuth token refresh" "JWT expiry" "auth middleware". - Start broad with
--compact(signatures only, fewer tokens), then narrow with--lang,--path,--type,--limit. - Add
--intent "<goal>"when the query is vague but the goal is clear. - Scope to a change with
--changed,--since <rev>, or--base <rev>when reviewing a diff. --deeprewrites the query through an LLM; use it only after normal search misses.
Treat hits as leads
- A search hit is a lead, not evidence. Before stating how something behaves, open the cited lines.
- Follow the call graph rather than re-searching:
vera references <symbol>on a promising hit answers "who drives this" in one step. - Cite
path:linefrom code you actually read. - After editing files, run
vera update .before searching again.
Recovery
| Symptom | Fix |
|---|---|
no index found |
vera index . |
| Stale results after edits | vera update . (or vera watch .) |
| A file is missing from results | vera explain-path path/to/file |
| Local model or ONNX error | vera doctor --probe, then references/troubleshooting.md |
| Missing local assets | vera repair |
| Install, API keys, backends | references/install.md |
| MCP server | references/mcp.md |
References
references/install.md: install, setup, API and local config,.veraignorerulesreferences/query-patterns.md: more query examples and rg guidancereferences/troubleshooting.md: common errors and fixesreferences/mcp.md: optional MCP server usage