Skip to content

Latest commit

 

History

History
275 lines (177 loc) · 17.8 KB

features.md

File metadata and controls

275 lines (177 loc) · 17.8 KB

Features

A tour of what Vera can do, grouped by task. For writing good queries, see the query guide. For every setting, see configuration.

Search

Search by behavior or by name

vera search "retry failed uploads with exponential backoff"
vera search "parse_config"

Each query runs two searches at once: keyword search (BM25), which is good at exact identifiers, paths, and config keys, and embedding search, which finds code that matches the meaning of the query even when the words differ. Vera merges the two result lists, then applies code-aware ranking. A keyword-only index (--full-text-only) uses BM25 alone. How Vera works explains each step.

Ranking prefers source files over docs and tests, leaves generated code out unless you pass --include-generated, and prefers the definition of a symbol over places that only mention it. Results are returned five at a time by default; change that with --limit or retrieval.default_limit.

Filters

Filter Example Effect
--lang --lang rust One language
--path --path "src/**/*.ts" Files matching a glob, relative to the repository root. Repeat it to match any of several patterns.
--type --type function One symbol type (function and method are interchangeable)
--scope --scope docs Only source (code, tests, and config), docs, runtime (extracted or bundled app code), or all. Without it, every indexed file except generated ones can match, and source ranks first. Generated files need --include-generated with any scope.
--include-generated Include minified and other generated files, which results leave out by default
--limit --limit 10 Number of results

Filters combine with AND. Multiple --path patterns combine with OR.

Several phrasings at once

vera search "OAuth token refresh" "JWT expiry handling" "auth middleware"

Vera runs each query and merges the results into one ranked list. This is cheaper than three separate calls and catches code that one phrasing would miss.

Intent

vera search "config" --intent "find where database connection strings are loaded"

--intent adds your goal to a short or ambiguous query so ranking can aim at what you need.

Deep search

vera search "how a request becomes a response" --deep

--deep is for questions whose answer is spread across several places. With a chat completion endpoint configured (VERA_COMPLETION_BASE_URL and VERA_COMPLETION_MODEL_ID, any OpenAI-compatible server including a local one), Vera first collects real symbol and file names from the index, asks the model to break the question into targeted sub-queries, runs them in parallel, and merges the results with the original query weighted highest. Without a completion endpoint, --deep follows the symbols named in the top results and searches for those instead.

Compact results

vera search "request validation" --compact

--compact returns signatures (name, parameters, return type) without bodies, so more results fit in fewer tokens. It is useful for a broad first look before reading specific functions. It also works with grep, references, and structural.

Search what changed

vera search "token validation" --changed       # modified, staged, and untracked files
vera search "token validation" --since HEAD~5  # files changed since a revision
vera search "token validation" --base main     # files changed on this branch

The same flags work with grep, structural, references, and overview. In a monorepo, the scope is limited to files inside the indexed directory.

Optional reranking

A reranker (cross-encoder) rereads the query together with each top candidate and reorders them. It is off by default, and vera setup --api turns it on when you configure an API reranker. In our screening, no tested local reranker improved on Vera's built-in ranking, while the Qwen API reranker paired with Qwen embeddings scored highest overall. Turn reranking on with vera config set retrieval.reranking_enabled true; see models for options.

Navigate code

Structural queries

vera structural definitions parse_config   # where a symbol is defined
vera structural env DATABASE_URL           # where an environment variable is read (omit the name for all)
vera structural routes                     # HTTP route registrations
vera structural sql                        # SQL execution sites
vera structural impls Loader               # types that implement, extend, or conform to Loader

These answer common questions directly from the index, without writing tree-sitter queries. impls reports explicit declarations (implements, extends, impl Trait for Type, and similar); it does not infer implicit interface satisfaction. routes and sql take no query term; narrow them with --path, --lang, or --scope.

Callers and callees

vera references parse_config             # who calls it
vera references parse_config --callees   # what it calls
vera references get --receiver app       # only calls written as app.get(...)
vera references parse_config --path src  # callers under src; also works with --callees

Call sites are extracted from the syntax tree at index time and matched by name, not resolved by a type checker. When several definitions share a name, the output lists the receivers the calls went through, and --receiver keeps just one.

--path uses the same directory and glob rules as search; repeat it to include several patterns.

Dead code candidates

vera dead-code

Lists functions and methods with no indexed callers, skipping common entry points such as main, new, and default. Treat the list as candidates: dynamic dispatch, reflection, generated code, and callers outside the index are invisible to name matching, so confirm before deleting.

Project overview

vera overview
vera overview --base main

Summarizes the project: languages, directory layout, entry points, symbol counts, complexity hotspots, and detected frameworks and conventions. It is a quick orientation for a person or an agent new to the codebase.

Regex search

vera grep "TODO|FIXME" --path "src/**"
vera grep "queryClient" -i --context 3

-C is short for --context after grep.

Regex search over indexed files, with the same filters and git scopes as vera search. It uses Rust regex syntax: | is alternation and \| matches a literal pipe. Use rg instead for files outside the index, counting matches, or find-and-replace work.

Indexing

vera index refuses to overwrite a usable index unless you pass --replace. Use vera update . to refresh changed files, or --replace for a deliberate full rebuild:

vera index . --replace

Dry run

vera index . --dry-run

Report files, bytes, estimated chunks, and rough indexing time without writing an index. Parsing and embedding are timed on samples, so the time is rough and leaves out index writes. Without --full-text-only, the dry run embeds up to 256 sampled chunks with your configured backend: a local model is loaded (and downloaded on first use), and an API backend receives those chunks like a normal index would send them.

Keyword-only index

vera index . --full-text-only

Build a keyword (BM25) index without configuring or loading an embedding model. Grep, structural queries, references, and overview work exactly as with an embedded index. Search ranks by keyword match only, so queries that describe behavior in plain words find less than they would with embeddings. vera update and watch mode keep the index keyword-only.

Run vera index . --replace to rebuild a keyword-only index with embeddings.

Symbol-aware chunks

For symbol extraction, line limits, and chunk splitting rules, see How Vera works: Parsing and supported languages.

Any chunk larger than indexing.max_chunk_bytes (24 KB by default) is split at line boundaries. That budget is separate from the embedding model's input window: local models truncate longer input to their maximum length, and an API provider with a smaller token limit can reject a chunk that fits the budget. If that happens, lower indexing.max_chunk_bytes and run vera index . again (add --replace if an earlier index already exists).

Updates and watch mode

vera update .                    # re-index only changed files
vera update . --max-files 250    # cap the work in one run
vera watch .                     # update automatically as files change

vera update re-parses only the files that changed, re-embedding them unless the index is keyword-only. It skips reading files whose recorded size, timestamps, and file identity still match, and hashes the rest; vera update --verify hashes every file. vera watch does the same in the background while you work, two seconds after the last change. update, watch, search, grep, and the other query commands find the nearest .vera/ index above the current directory, so they work from any subdirectory. The search stops at a linked worktree root.

Search warns when the index is behind the working tree and tells you how many files changed.

Linked worktrees

In a linked git worktree without an index, Vera seeds an independent index from the indexed main checkout, then incrementally updates it before returning results. Added, changed, and deleted files reflect the worktree, not the main checkout, including worktrees created inside the main checkout's directory. Only changed content needs new embeddings, using your active backend. vera update --max-files cannot cap this first seed. If seeding or updating fails, run vera index . from the worktree root.

Querying another index

Index a dependency source tree once, then use -C <DIR> (or --directory <DIR>) before the subcommand to query it without leaving your project:

vera index ~/.cargo/registry/src
vera -C ~/.cargo/registry/src search "retry backoff"

Each tree keeps its own .vera/ index. With MCP, use the optional repo argument instead.

To search your project and other indexed trees in one call, repeat --also:

vera search "retry backoff" --also ~/.cargo/registry/src

Each index is searched with its own mode (hybrid or keyword-only) and the same filters; absolute --path filters are rewritten for each tree. Scores from different indexes are not comparable, so results are merged by rank, and the current project gets a one-place head start: its first two results come before the other tree's first. Results from another tree show absolute paths, and --json adds a repo field to every result while file_path stays relative to its tree. When only one distinct index ends up searched (for example, --also names the current project), output keeps the single-index format. Up to 8 indexes can be searched at once. --also never creates an index for the extra trees (the current project keeps the usual first-run prompt) and cannot be combined with --changed, --since, or --base. A directory that is missing or not indexed stops the search with an error. If an extra index fails during the search, a warning goes to stderr and the other results are still shown. With --deep and a completion endpoint, the query is expanded once and reused for every index; without one, each index follows symbols on its own.

Choosing what gets indexed

Vera skips anything in .gitignore, plus common build and dependency directories (node_modules, target, dist, .venv, and others). For more control, add a .veraignore file in gitignore syntax; put #include .gitignore on its first line to keep the gitignore rules and add your own on top. One-off options: --exclude <glob>, --no-ignore, and --no-default-excludes.

If a file you expect is missing, ask Vera why:

vera explain-path src/generated/schema.ts

It reports the deciding rule: a default exclude, an ignore file, the size limit, binary detection, and so on.

Index health

vera stats shows file, chunk, and language counts, the index size, and parse health: files where tree-sitter found syntax errors, files that fell back to line chunking, and files that failed to parse. Problems show up here instead of quietly lowering search quality. Add --json for scripts.

Indexing with an API backend

API indexing sends requests in parallel, retries timeouts and rate limits with backoff, and honors Retry-After. If a run fails partway, the embeddings already received are saved in .vera.resume/, and re-running the same vera index command (vera index ., or vera index . --replace when rebuilding an existing index) reuses them instead of paying for them again. The existing index stays usable until a new build finishes.

Indexing shows a progress display in a terminal. In CI or agent runs, it prints a short progress line to stderr every 10 seconds on slow runs, and --json prints a summary with file, chunk, request, retry, and timing counts.

Output

Flag Output
(default) Markdown code blocks labeled with path, line range, and symbol
--compact Signatures only
--json Compact JSON
--raw Verbose, human-readable output with every field
--timing Timings on stderr. search reports index lookup, freshness check, setup, each search stage, output, and the end-to-end total; grep and structural report index lookup, freshness check, search, output, and total

--json, --raw, and --timing can go before or after the subcommand. vera search --json --rerank-status also reports whether results were reranked and, if not, why.

Search output has no length limit by default. Set retrieval.max_output_chars (or VERA_MAX_OUTPUT_CHARS) to cap the total characters; lower-ranked results are trimmed first, at a line boundary.

Agent integration

  • Skill files (recommended for shell-capable agents). vera agent install writes the Vera skill to .agents/skills/ and client-specific skill directories, globally or per project. Agents see a short discovery summary and load full command instructions on demand, including routing rules for when vera search, vera structural, vera references, rg, or direct file reads fit best. See installation.
  • Project instructions. In a terminal, the installer can maintain a short Vera routing block in a repository's AGENTS.md, CLAUDE.md, or editor rules file between <!-- vera:begin --> and <!-- vera:end --> markers.
  • Keeping skills current. vera agent sync refreshes outdated skill copies and managed project sections. Upgrades run this automatically.
  • MCP server. vera mcp exposes search_code, regex_search, structural_search, find_references, get_overview, explain_path, and get_stats over stdio, auto-indexing on first search and watching for file changes while running. See MCP.

Models and backends

  • Local CPU (default). Potion Code (minishlab/potion-code-16M-v2) runs on any supported CPU after a one-time ~32 MB download, with no GPU, ONNX Runtime, or API account.
  • API mode. Any OpenAI-compatible embedding endpoint plus optional generic or Voyage-style reranking. Pairing qwen/qwen3-embedding-8b and qwen/qwen3-reranker-8b (built-in OpenRouter preset, or separate OpenAI-compatible hosts) produced our highest measured retrieval and agent context-efficiency results.
  • Local GPU / custom ONNX. Jina ONNX backends for CUDA, ROCm, CoreML, DirectML, and OpenVINO, plus custom Hugging Face or local ONNX models. Batch sizes adapt to sequence length and memory; --low-vram forces conservative settings on small GPUs.
  • Switching. vera backend changes the backend without rerunning the full setup wizard.

Details and measurements: models and backends.

HTTP inference server

vera serve --port 3000

vera serve runs Vera's local models behind an HTTP API so other tools, or other machines, can use them: POST /v1/embeddings (OpenAI format), POST /v1/rerank (Cohere and Jina format), and GET /v1/health. It listens on 127.0.0.1 by default. Use --host to bind elsewhere and --api-key (or VERA_SERVE_KEY) to require a bearer token.

The embedding model loads at startup. The reranker is configured at startup and loads on its first request; a failed load can be retried by a later request. Models unload after 300 seconds without requests; change that with --idle-timeout, or pass a negative value to keep them loaded.

Vera itself can be one of those clients. Opening an index takes milliseconds, but loading a local ONNX model can take seconds, and each CLI call or MCP session loads it again. Running vera serve --idle-timeout -1 once and pointing Vera at it in API mode keeps one model loaded for every command, session, and index on the machine (vera serve --help shows the client setup).

Maintenance

Command What it does
vera doctor Checks configuration, model files, the index, and whether a newer release exists. --probe also loads the backend to test it. Exits 1 on failure.
vera repair Re-downloads missing or damaged model files and runtimes.
vera upgrade Shows the update plan; --apply runs it.
vera config Shows settings; vera config get and vera config set read and change them.
vera uninstall Removes Vera's binary, models, config, and agent skills. Project indexes stay.

Platforms

Native binaries for Linux (x86_64, aarch64), macOS (x86_64, Apple Silicon), and Windows (x86_64), plus a static musl build for Linux systems without glibc. Install through npm, Bun, uv, pip, a prebuilt archive, Docker, or from source. See installation.