Kivgraph

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.

https://github.com/user-attachments/assets/b8410905-323d-4caf-9d7b-57c50ffca48c

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

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 bundled AST worker in fallback mode; those inferred references are CANDIDATE, never EXACT. Exact Python mode uses the bundled Pyright LSP adapter with an installed Pyright/BasedPyright server. Dart uses the Dart Analysis Server supplied by the Dart or Flutter SDK.
• Semantic dependencies: Python and Dart imports can publish a package dependency when exactly one registered provider owns the requested package; symbol-level cross-repository edges require an explicit provider identity.
• Surface: thirteen read-only tools over STDIO, plus two consent-gated mutations (index_project and start_index_project). The contract is docs/protocol/mcp-surface-v3.md.
• Storage: LadybugDB is canonical; queries are served from an immutable HotSnapshot published atomically, never from the database.
• Platforms: linux/amd64, darwin/arm64 and windows/amd64.
• Viewer: kivgraph ui serves a read-only 3D view of the published graph.

Installation

Install the MCP with one script

The installer detects the platform, downloads the latest published MCP release for it, verifies both the release archive and the bundle checksums, and installs it without requiring Go or pnpm. The release contains the Go server, the pinned LadybugDB library, the TypeScript worker, the bundled Python AST worker, the pinned rust-analyzer, the grammar manifest and the web viewer, whose assets are 2.3 MB of the bundle. scripts/build-bundle.sh --mcp-only produces a bundle without the viewer for anyone who wants one. --slim goes further for anyone packaging an .mcpb: it leaves out the pinned rust-analyzer and every symbol a debugger would read, which is 46.3 MB packaged against 24.9 MB. It downloads nothing later, so that bundle reads Rust only where the machine already has an analyzer on its PATH.

Published bundles: Linux amd64, macOS arm64 and Windows amd64.

Runtime requirements: Bash on Linux and macOS or PowerShell 5.1 or later on Windows, Node.js 22 or later, Python 3.10 or later when indexing Python, and on the POSIX platforms curl, tar, and sha256sum or shasum. The bundle carries its own rust-analyzer; indexing Rust repositories additionally needs cargo on the PATH, and indexing Dart needs the Dart or Flutter SDK. On Windows the installer also installs the Visual C++ redistributable, without which kivgraph.exe does not start.

On macOS the binaries are not notarized. A release downloaded with curl is not quarantined and runs; a copy downloaded with a browser needs xattr -dr com.apple.quarantine. See docs/development/macos.md.

Install the latest release in one command. On Linux and macOS the same line covers both, because the installer reads uname and picks its own archive:

curl -fsSL https://kivgraph.dev/install.sh | bash

On Windows, where install.sh cannot run because there is no POSIX shell:

irm https://kivgraph.dev/install.ps1 | iex

install.ps1 is a second implementation of the same pre-extraction checks, and internal/release/install_parity_test.go fails when either script grows a check the other lacks. Piping it into Invoke-Expression turns its #Requires -Version 5.1 into a comment; download it to a file and run it as one to keep that guard.

From a checkout, either installer can be run directly:

./scripts/install.sh

To install a specific release instead of the latest one:

KIVGRAPH_VERSION=v0.9.10 ./scripts/install.sh

The script installs the bundle in ~/.local/opt/kivgraph and puts launchers in ~/.local/bin; on Windows it is %LOCALAPPDATA%\Programs\kivgraph and %LOCALAPPDATA%\Programs\kivgraph-bin. It never modifies a registered repository, creates an index, or replaces configuration files. To use a different location, set KIVGRAPH_INSTALL_ROOT and KIVGRAPH_BIN_DIR.

Add the launcher directory to the current shell and verify both runtimes:

export PATH="$HOME/.local/bin:$PATH"
kivgraph version
kivgraph-ts-worker <<'EOF'
hello
EOF

Check for a newer release or update the installed bundle:

kivgraph update --check
kivgraph update

Bundle replacement is atomic, preserves the configuration and graph state, verifies the release and bundle checksums, and replaces the installed bundle. The post-install runtime refresh may partially complete, fail, and make the command exit non-zero. It also restarts an installed supervised daemon and refreshes Kivgraph-managed user hooks, skills and MCP registrations. A stale supervisor returns an error and is not restarted. Missing, foreign and project-scoped integrations are left alone. Client-owned serve and ui processes still need a restart, or --stop, to use the new binary.

Development builds use a separate prerelease channel. Install one explicitly, then select that channel for later checks:

release=vX.Y.Z-dev.N
curl -fsSL \
  "https://github.com/Luqueee/kivgraph/releases/download/$release/install.sh" |
  KIVGRAPH_VERSION="$release" bash
kivgraph update --channel dev

For a prerelease binary, omitting --channel already follows dev; stable installations continue to follow the stable channel. KIVGRAPH_UPDATE_CHANNEL can be used instead of the flag, including for the interactive update notice.

To remove the installed bundle and launchers without deleting configuration, repository registrations or graph state:

uninstall_url=https://github.com/Luqueee/kivgraph/releases/latest/download/uninstall.sh
curl -fsSL "$uninstall_url" -o /tmp/kivgraph-uninstall.sh
bash /tmp/kivgraph-uninstall.sh

Use bash /tmp/kivgraph-uninstall.sh --yes for a non-interactive removal. Windows users can run the corresponding uninstall.ps1 with PowerShell.