kivgraph

# 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.

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](https://github.com/Luqueee/kivgraph/tree/main/landing/src/content/docs)
for installation, MCP clients, code intelligence, repository relationships and
workspace code graphs. The published site is configured separately from the
release bundle; this link remains valid from every checkout.

## What each tool answers

| the question | the tool |
| --- | --- |
| who calls this, what references this | `find_references` |
| 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` |
| 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` |

Ten read-only tools, plus one consent-gated mutation (`index_project`) that a
client has to authorize before it 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`](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:** ten read-only tools over STDIO, plus one consent-gated
  mutation (`index_project`). The contract is
  [docs/protocol/mcp-surface-v3.md](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.

## Requirements

- Go 1.26 or later to build from source. The indexer type-checks with the
  `go/types` linked into the binary, so it can only read repositories and
  dependencies written for its own language version or older; `kivgraph doctor`
  reports that ceiling.
- Indexing Rust needs `cargo` and `rust-analyzer`. The release bundle carries
  the analyzer; it does not carry a Rust toolchain.
- Indexing TypeScript needs Node.js 22 or later for the worker.
- Indexing Python needs Python 3.10 or later for the bundled worker. It is a
  syntax-aware fallback and reports dynamic or unresolved names explicitly;
  exact mode additionally requires a Pyright-compatible language server.
- Indexing Dart needs the `dart` executable; a Flutter installation supplies
  it. The loader uses the Analysis Server protocol and does not modify the
  Flutter project.

## 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.

Published bundles: Linux `amd64` and macOS `arm64`.

Runtime requirements: Bash, Node.js `22` or later, Python 3.10 or later when
indexing Python, `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 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](docs/development/macos.md).

Install the latest release in one command:

```bash
curl -fsSL https://github.com/Luqueee/kivgraph/releases/latest/download/install.sh | bash
```

From a checkout, the same installer can be run directly:

```bash
./scripts/install.sh
```

To install a specific release instead of the latest one:

```bash
KIVGRAPH_VERSION=v0.9.1 ./scripts/install.sh
```

The script installs the bundle in `~/.local/opt/kivgraph` and puts launchers
in `~/.local/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:

```bash
export PATH="$HOME/.local/bin:$PATH"
kivgraph version
kivgraph-ts-worker <<'EOF'
hello
EOF
```
Check for a newer release or update the installed bundle:

```bash
kivgraph update --check
kivgraph update
```

The update is atomic, preserves the configuration and graph state, verifies
the release and bundle checksums, and replaces only the installed bundle.
Restart the MCP client after updating so it launches the new binary.

When `kivgraph` is invoked without a command from an interactive terminal, it
checks for a newer release with an 800 ms timeout and a 24-hour cache in the
platform cache directory (`$XDG_CACHE_HOME` on Linux and
`$HOME/Library/Caches` on macOS), under `kivgraph/update-check.json`.
The optional check never blocks the command when the network is unavailable.

Interactive command output uses semantic ANSI colors when the destination is a
terminal. Set `NO_COLOR` or redirect output to keep it plain.

### Configure an MCP client and install the skill

The release installer does not edit client configuration automatically. After
installing Kivgraph, run the integration commands without `--target` to detect
the coding agents present on this machine and select one or more of them:

```bash
kivgraph mcp install --scope user
kivgraph skill install --scope user
```

Kivgraph checks each client's known local configuration or installation roots
and marks detected agents. Use `↑`/`↓` (or `j`/`k`) to move, `space` to toggle
an agent, `a` to select all, `n` to select none, `Enter` to confirm, and `q` or
`Esc` to cancel. If none is detected, the selector starts with no agents
selected. Use `--target` only for scripted, non-interactive installation.

Supported MCP targets are `claude-code`, `claude-desktop`, `codex`, `opencode`,
and `oh-my-pi`. Supported skill targets are `claude-code`, `codex`, `opencode`,
and `oh-my-pi`; Claude Desktop has no local skill target. The default scope is
`user`; use `--scope project` for project-local configuration. Use `--dry-run`
to inspect a plan without writing. Existing incompatible entries stop with an
error; `--force` is required to replace or remove one. Existing files are
written atomically with mode `0600` and receive a
`*.kivgraph.bak` backup before replacement or removal.

Inspect or remove a registration explicitly:

```bash
kivgraph mcp status --target claude-code --scope user
kivgraph mcp remove --target claude-code --scope user
kivgraph skill status --target claude-code --scope user
kivgraph skill remove --target claude-code --scope user
```

Initialize and publish a graph before starting the MCP server:

```bash
kivgraph init \
  --repository project=/absolute/path/to/project \
  --languages go,typescript,rust
kivgraph doctor
kivgraph index --full
```

`init` writes a self-contained configuration: with `--config` pointing
elsewhere, its state, cache and registry hang off that d