Luqueee/kivgraph

> [!NOTE]
> **Kivgraph began as a research project.** It explored whether a local semantic
> code graph could reduce the amount of context coding agents need to inspect.
>
> The resulting tool remains useful for structured code navigation,
> cross-repository relationships, and impact analysis. However, the research
> **did not demonstrate a reliable net token saving over long, end-to-end agent
> conversations**. While some isolated queries can use substantially fewer
> tokens than grep plus file reads, those savings did not consistently
> translate into lower token usage across realistic long-running agent
> workflows.
>
> The benchmark results and their limitations are preserved in
> benchmarks/, including the
> end-to-end agent benchmark.
Kivgraph is a local **cross-repository code intelligence MCP server for AI
coding agents**. It builds a canonical semantic code graph across multiple
registered repositories and answers questions about symbols, repository
relationships, callers, dependencies and change impact.
Watch the Kivgraph UI demo video
kivgraph ui — read-only 3D view of the published graph.
It indexes a corpus once and serves an immutable graph: the edges are resolved
by go/types, the TypeScript checker and rust-analyzer, not by matching
names. That is the difference from a search tool, and it is what makes an empty
answer worth something — an empty reference list means **nobody calls it**, not
that nothing was found, and grep cannot tell those apart.
Kivgraph is focused on semantic code relationships, not automatic discovery of
every HTTP, gRPC, Kafka or database runtime flow between services.
Documentation
Read the Kivgraph user documentation for installation,
MCP clients, code intelligence, repository relationships and workspace code
graphs. The same pages are the source of landing/src/content/docs in this
checkout, which is what a reader on a fork or without a network still has.
What each tool answers
| the question | the tool |
| --- | --- |
| who calls this, what references this | find_references |
| who implements a type or method | find_implementations |
| what breaks if I change it | get_blast_radius |
| what does this reach outward | trace_dependencies |
| who uses it from another repository | find_cross_repo_consumers |
| where is it declared | find_symbol |
| I don't know what it is called, what files to open | find_by_intent |
| what is declared in this package | get_file_outline |
| give me the code of these symbols | get_source |
| everything about this one symbol | get_symbol |
| what is indexed, and is the graph current | list_repositories, graph_status |
| how is an asynchronous index progressing | get_index_status |
Thirteen read-only tools, plus two consent-gated mutations (index_project and
start_index_project) that a client has to authorize before either can register
a repository or publish a generation.
Every row that names a symbol carries its repository, path, qualified name and
line range, so it can be opened without a second call, and every tool accepts
that triple in place of an opaque key.
**Where it loses.** A rare name in one small repository is cheaper with grep,
and indexing a small file costs more than reading it. It wins on common names,
on transitive impact, on consumers in another repository, and on proving an
absence. Measured over 29 questions against a 37-repository corpus
(benchmarks/graph-tools-comparison/results-all.json, commit 954b9eb,
tokenizer o200k_base): 35,961 tokens for Kivgraph against 267,980 for
grep plus reading, both exact on 28 of the 29, median 5.95x per question in
Kivgraph's favour. grep is cheaper on 5 of those 29, all of them at full
recall on both sides: T1_go_trivial asks for a name the corpus declares
twice, and there grep costs 0.53x what Kivgraph does.
A second harness, benchmarks/mcp-token-cost, compares against the host's own
tool output captured verbatim, but it runs on Kivgraph's own single repository
of 13,222 symbols: 7.64x on the answers themselves and 1.60x over a whole
session, against a 2.41x floor set by the source bodies both arms pay for.
Status
Released and in use. kivgraph version reports the published release; the
backlog and the acceptance gate of every phase are in TASKS.md.
- **Languages:** Go, TypeScript, Rust, Python and Dart. Python uses the