Know what breaks before your coding agent changes it.

One symbol, three questions, and the answer your agent gets back. Every file count, hop, edge kind, line range and token figure below is from one run of the published benchmark, and each panel names the question it answers.

The corpus behind it is 37 private repositories, so the repository, file and symbol names are substituted. The structure is not: same repositories, same row in each, same language, same numbers. Every figure here can be checked against results-all.json in the repository.

the whole benchmark, method and losses included

withBackoff is declared seven times in the benchmark corpus, in five repositories and two languages — two of them the same file path in two different repositories. The graph holds twenty-two symbols with that name — the other fifteen are TypeScript barrel re-exports — and the identifier appears in twenty-two files. Identical text, seven different symbols.

That corpus is private, so the repository, file and symbol names below are substituted; the seven declarations, the five repositories, the language split and the line numbers are the captured ones. The 129-token cost of the refusal was measured against the real identifiers — a token count is a function of the strings it encodes. The two transcripts on the right are literal: they come from Kivgraph's own repository.

tools/call find_references{"name":"withBackoff"} AMBIGUOUS_SYMBOL: name "withBackoff" declares 7symbols; repeat with the repository and path ofthe one you mean: config-lib:src/retry.ts:41, ... # 129 tokens, and the answer is the next call

tools/call find_cross_repo_consumers{"repository":"kivgraph","path":"internal/facts/facts.go", "qualified_name":"MergeAll"} # total 0   returned 0   consumers nullguidance: no repository in the published graph consumes this          symbol. Check graph_status if a consumer is          registered but was not indexed, and          find_references for uses inside its own          repository

1. 01Edges come from go/types, the TypeScript checker, rust-analyzer and the Dart analysis server. Never from matching a name, a path, an alias or a single plausible candidate.
2. 02Asked by a name that means seven things, the server refuses and names the seven. It costs 129 tokens and the next call is a copy of one row.
3. 03Two homonymous symbols are two symbols, with different kinds, different packages and different ranges.
4. 04A reference that cannot be resolved is published as UNRESOLVED with its reason, repository and language rather than dropped, and CANDIDATE is a different result from EXACT.

how resolution works, per language

the edge

REEXPORTS, EXACT_TYPECHECKED, resolved by the TypeScript checker of the providing package — not by the two packages sharing a name.

what grep saw

Nothing. The consuming file never spells the symbol, so no text search reaches it. Two of the three consumers were found; this was the third.

what a language server sees

Its own workspace. A cross-repository consumer is outside it, so the question cannot be asked there at all.

kept apart on purpose

The same answer carried 22 package-level rows. They are reported separately and never counted as uses: a package depending on a package is not a symbol using a symbol.

The installer puts the bundle in ~/.local/opt/kivgraph with launchers in ~/.local/bin, verifies the release checksum and then the bundle's own, and stops there: it configures no client, writes no configuration and indexes nothing. These four commands are the rest.

Register, check, index, connect. Nothing answers until a generation exists, so that order is the whole setup.

1. 01register a repository

   copy

   $ kivgraph init \
     --repository project=/absolute/path/to/project \
     --languages go,typescript,rust

   --repository NAME=PATH may be repeated. The name is compared exactly, and it travels inside the stable keys of everything the repository declares.

2. 02check the machine

   copy

   $ kivgraph doctor

   doctor reports the configuration, the toolchains it found and the state of the published graph. It names the language version ceiling this binary type-checks Go with, which is not the go on your PATH.

3. 03index and publish

   copy

   $ kivgraph index --full

   The pass analyses every registered repository, validates the canonical graph and publishes it as a new generation. Publication is atomic: a candidate that fails integrity or validation never becomes CURRENT, and the previous generation keeps serving.

4. 04register the client

   copy

   $ kivgraph mcp install --scope user

   Detects the coding agents on this machine and writes the entry after you select them. Supported targets: claude-code, claude-desktop, codex, opencode and oh-my-pi.

{
  "mcpServers": {
    "kivgraph": {
      "command": "/home/user/.local/bin/kivgraph",
      "args": [
        "serve",
        "--config",
        "/home/user/.config/kivgraph/config.yaml"
      ]
    }
  }
}

tools/call index_project        # confirmed unset PERMISSION_REQUIRED: user approval is required; confirm theoperation before setting confirmed=true

• the quickstart in full
• MCP clients
• indexing guide
• configuration
• troubleshooting

One authority per language, and it is the language's own. An edge is never created from a name — but the five are not equal, and the difference is printed on each row rather than left for you to discover after indexing.

• #Go

  type-checked

  go/types, linked into the binary

  Packages are loaded through go/packages with the build tags you configure, and resolution comes from a full type universe. The unit of analysis is the module.

  The binary type-checks only up to the language version of the toolchain that built it. A module above that ceiling is rejected by name.

• #TypeScript

  type-checked

  the @kivgraph/ts-worker tsserver process

  Each package.json project is analysed by the TypeScript checker itself. A cross-package symbol is placed by the provider's declaration map, or by asking the provider's own checker what its module exports.

• #Rust

  type-checked

  rust-analyzer scip, bundled and pinned

  The authority is rust-analyzer, invoked once per Cargo workspace. Tree-sitter contributes the syntactic class of a use and the declared visibility, never identity.

  core, std and alloc are not indexed, so derive, operator overloading, ? and standard-library calls produce no edges.

• #Dart

  analyzer-resolved

  the Dart or Flutter Analysis Server

  Dart and Flutter source is indexed through the SDK analysis server. Local declarations, navigation references and calls are published with analyzer evidence, while external packages are reported as unresolved unless their source is indexed.

  Tests and generated files are excluded by default and can be enabled in configuration.

• #Python

  exact only with a configured analyzer

  the configured semantic worker or bundled AST worker

  A configured semantic provider — a Pyright-compatible language server — can publish exact declarations and references. Without one, the bundled worker covers Python and stub files without guessing dynamic names, and everything it infers stays CANDIDATE rather than becoming EXACT.

  Dynamic imports, monkey patching and unresolved runtime attributes remain explicit candidates or unresolved facts.

how resolution works

Every answer on this page comes out of one immutable snapshot, published atomically and never queried from the database behind it. That snapshot is inspectable two ways: as the numbers below, and as a read-only 3D view of the same structure. It is a debugging surface, not the product — but it is the fastest way to see whether the graph your agent is answering from is the graph you meant to build.

More answers in the Kivgraph FAQ, the limits and on GitHub.