Vaelor

Give your coding agent a memory of the codebase it can't get from grep.

Vaelor is the open-source engine behind Krolik: a self-hosted MCP server that parses, graphs, and watches a codebase so an AI agent doesn't have to re-discover it every session. Tree-sitter AST parsing across 16 languages feeds a call graph with type-aware Go resolution (go/types), a persistent Apache AGE knowledge graph, and hybrid semantic search. review_pr remembers what broke last time a symbol was reviewed. debug_investigate correlates a Prometheus alert and a Jaeger trace back to the function that caused it.

Quick Start in three commands. If it's useful, a star helps the next person find it.

Why not just grep, or a code index?

Every code-search tool finds the function. Fewer tell an agent what else breaks when it changes, and fewer still remember your last review or your last production incident.

Vaelor's Apache AGE graph carries PageRank, community, and surprise scores computed from your actual call graph, and those scores feed understand, prepare_change, and review_pr directly. review_pr also persists a verdict per symbol from the real GitHub review outcome, and understand surfaces it automatically the next time anyone touches that symbol, so a "this broke in review" fact travels with the code instead of living in someone's memory. debug_investigate goes further: it fuses a live Prometheus alert and a Jaeger trace with the same call graph into a ranked file:function hypothesis, so an incident resolves to code, not just a dashboard alert. An agent's sense of which change is risky comes from the shape of your actual codebase, recomputed on every graph update.

Quick Start

Docker (recommended)

docker build -t vaelor .
docker run -p 8897:8897 \
  -e LLM_API_BASE=http://host.docker.internal:8317/v1 \
  -e LLM_API_KEY=your-key \
  vaelor

From source

Requires Go 1.24+ and a C compiler (CGO for tree-sitter grammars).

make build    # → bin/vaelor
./bin/vaelor

Register as an MCP server

claude mcp add -s user -t http vaelor http://127.0.0.1:8897/mcp

Try it

No local clone needed: understand and call_trace take a GitHub repo directly and fetch it on the first call. That first call indexes the repo, so give it a few seconds; after that it's cached. Start with a small repo:

{
  "tool": "call_trace",
  "arguments": {
    "repo": "gorilla/mux",
    "symbol": "ServeHTTP",
    "direction": "callees",
    "depth": 2
  }
}

Walks Router.ServeHTTP through the routing path with cycle detection — no Docker volume mount and no DATABASE_URL required.

No LLM_API_KEY yet? Most tools still run: they skip only the narrative and ranking layer. See LLM dependency for exactly what degrades and what doesn't.

What it does

Understand a codebase

explore: fast, no-clone overview for remote repos. understand: symbol deep-dive covering callers, callees, complexity, dead-code score, and any prior review verdicts on that symbol. code_research: BM25F plus embeddings plus graph expansion for 10k+ file monorepos.

Know what a change will break

impact_analysis: configurable blast-radius depth (default 5), hotspots reordered by churn. prepare_change: impact analysis and dead-code check in one call. call_trace: bidirectional call chains with cycle detection and an LLM narrative.

Search by meaning, not keyword

semantic_search: pgvector plus hybrid RRF plus 1-hop graph expansion. symbol_search, code_search, github_code_search (no clone required).

Review and remember

review_pr / review_delta: differential blast radius between git refs, posting to GitHub and persisting a per-symbol learning on approval or rejection. code_compare: structural diff between two repos covering architecture, API design, quality. rewrite: structural AST search-replace across 16 languages, dry-run first.

Debug what's actually running, not just what's in the diff

debug_investigate: 7-phase incident root cause, from metric spikes and failed traces through symbol resolution, callgraph walks, LLM fusion, and runtime binary drift, ranked to a file:function. fleet_versions: diffs the image tags pinned in source against what's actually deployed. dataflow: taint tracking, dead stores, SQL/command-injection sinks. dead_code and code_health: an A-F grade covering complexity, test coverage, dependency freshness, OSV vulnerabilities.

Also worth knowing about

find_duplicates: finds near-duplicate symbols in a repo via semantic similarity (needs EMBED_URL + DATABASE_URL). suggest_reviewers: ranks reviewer candidates for a PR's file paths from authorship, co-change coupling, and recency.

That's the headline set, not the whole one. The table below documents what's stable; call tools/list on a running server for the complete, current one.

Tool Reference

The stable, documented set. The server exposes a few more; tools/list on a running instance is the authoritative, current list.

Optional sidecars. dead_code and code_health sharpen from AST-only heuristics to confidence-scored results when ox-codes (Rust) is running alongside. semantic_search needs an embedding endpoint; ox-embed-server (ONNX embeddings, cross-encoder rerank, SPLADE) is the reference one. Neither is required to run Vaelor, and every tool without them still returns a real result, just a coarser one.

Learnings loop

review_pr (with dry_run=false) writes one learning per changed symbol on a completed GitHub review: APPROVE maps to good, REQUEST_CHANGES maps to bad, everything else is neutral. The dry-run path writes a risk_level on the same record. The next time anyone calls understand on that symbol, Store.Nearest looks up the closest prior learnings and attaches them as prior_learnings on the result, no extra call needed. The loop is gated on LEARNINGS_DATABASE_URL (falls back to DATABASE_URL); with neither set, it silently no-ops instead of erroring.

Graph signal ecosystem

Two graph representations cooperate through internal/graphx without either package knowing about the other, so every consumer below degrades to byte-identical output when there's no graph snapshot yet.

Runtime version awareness

When a production bug lives at the deployed-binary level rather than in source (pinned tag drift, sibling-host divergence, a silent auto-update), Vaelor can probe running containers and diff them against what the indexed repo pins.

• fleet_versions: the explicit tool. Pass host (defaults to the local Docker socket) and an optional service filter. Returns a per-target diff: Match / TagDrift / DigestDrift / OnlySource / OnlyRuntime / Unresolved.
• debug_investigate Phase 7: runs automatically when an investigation starts with host set. Drift enters the LLM prompt priority-capped at the top 20 non-Match diffs, sorted TagDrift > DigestDrift > Unresolved > OnlyRuntime > OnlySource.

SSH probe

Reaching a remote host uses the system ssh binary directly; Vaelor doesn't maintain its own SSH stack, so ~/.ssh/config (ProxyJump, agent, identities, port, known_hosts) is the single source of truth. The driver is off by default: enable with GOCODE_FLEET_SSH_ENABLE=true. Commands on the remote host are limited to an internal allowlist, exactly docker ps --no-trunc --format={{json .}}, with filter values regex-validated before any exec call.

Configuration

Full environment reference (SearXNG, GitLab, fallback-model chains, fleet SSH, indexing tuning): CLAUDE.md.

LLM dependency

LLM_API_KEY is optional. The server starts and most tools operate without it:

Set LLM_API_BASE + LLM_API_KEY + LLM_MODEL to run every tool at full capability. Any OpenAI-compatible endpoint works: OpenAI, Anthropic via proxy, a local Ollama instance.

Architecture

cmd/vaelor/     : MCP server, tool handlers (one file per tool)
internal/
  parser/        : tree-sitter AST parsing, 16 language handlers
  ingest/        : repo cloning, file walking, gitignore filtering
  clean/         : code cleaning for LLM context
  render/        : rendering modes (signatures, skeleton, focused)
  analyze/       : analysis orchestration
  compare/       : structural diff engine
  callgraph/     : call chain tracing (BFS/DFS, bidirectional), type-aware for Go
  codegraph/     : Apache AGE knowledge graph
  embeddings/    : semantic search: pgvector store, embed pipeline, hybrid RRF, graph expansion
  learnings/     : pgvector-backed store for prior review findings
  investigate/   : Prometheus + Jaeger correlation for debug_investigate
  fleet/         : deployed-vs-source container image drift
  github/        : GitHub API (search code/issues/repos, metadata)
  llm/           : LLM client with retry and fallback keys
  cache/         : generic LRU cache with Redis L2

Analysis Modes

Deep mode (default). Clones the repo, walks the file tree, parses ASTs with tree-sitter, builds a symbol table, and answers questions via LLM. depth controls context size (overview/module/deep), mode controls rendering (signatures/skeleton/focused).

Quick mode (mode=quick). GitHub Code Search API, no cloning. Returns matching code fragments, optionally LLM-summarized. mode=raw skips the LLM step entirely.

Issues/PRs mode (type=issue or type=pr). Searches GitHub Issues/Pull Requests. Structured results with state, labels, author, and an LLM read on trends.

Webhook

POST /webhook/github on the MCP port (:8897) handles pull_request events (opened/synchronize/reopened). Requires X-GitHub-Event and X-Hub-Signature-256 headers and GITHUB_WEBHOOK_SECRET set. REVIEW_POST_ENABLED=true posts the review to GitHub; otherwise it dry-logs. Expose it through your existing tunnel and register it in the repo's webhook settings.

Transport

• HTTP (default): streamable HTTP on MCP_PORT
• Stdio: ./vaelor --stdio for pipe/SSH access

Build

make build      # Build binary (CGO required)
make lint       # Run golangci-lint
make test       # Run tests
make deploy     # Docker build + deploy

License

Apache 2.0, Copyright 2026 Anatoly Koptev.

Contributing

See CONTRIBUTING.md for adding a new tool or a new language.

For security vulnerabilities, see SECURITY.md. Please don't open a public issue for those.

If Vaelor saves your agent from re-discovering the same fact about your codebase twice, a star helps the next person find it before they build a fifth MCP code-search server from scratch.