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, direct callers paged via max_callers+offset (default 100) with optional include_snippets call-site lines. 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_codeandcode_healthsharpen from AST-only heuristics to confidence-scored results when ox-codes (Rust) is running alongside.semantic_searchneeds 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. Passhost(defaults to the local Docker socket) and an optionalservicefilter. Returns a per-target diff:Match/TagDrift/DigestDrift/OnlySource/OnlyRuntime/Unresolved.debug_investigatePhase 7: runs automatically when an investigation starts withhostset. Drift enters the LLM prompt priority-capped at the top 20 non-Matchdiffs, sortedTagDrift>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 --stdiofor 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.