{
  "markdown": "# Kivgraph\n\n[![kivgraph MCP server](https://glama.ai/mcp/servers/Luqueee/kivgraph/badges/score.svg)](https://glama.ai/mcp/servers/Luqueee/kivgraph)\n\nKivgraph is a local **cross-repository code intelligence MCP server for AI\ncoding agents**. It builds a canonical semantic code graph across multiple\nregistered repositories and answers questions about symbols, repository\nrelationships, callers, dependencies and change impact.\n\nhttps://github.com/user-attachments/assets/b8410905-323d-4caf-9d7b-57c50ffca48c\n\n<p align=\"center\">\n  <em><code>kivgraph ui</code> — read-only 3D view of the published graph.</em>\n</p>\n\nIt indexes a corpus once and serves an immutable graph: the edges are resolved\nby `go/types`, the TypeScript checker and `rust-analyzer`, not by matching\nnames. That is the difference from a search tool, and it is what makes an empty\nanswer worth something — an empty reference list means **nobody calls it**, not\nthat nothing was found, and `grep` cannot tell those apart.\n\nKivgraph is focused on semantic code relationships, not automatic discovery of\nevery HTTP, gRPC, Kafka or database runtime flow between services.\n\n## Documentation\n\nRead the [Kivgraph user documentation](https://kivgraph.dev/) for installation,\nMCP clients, code intelligence, repository relationships and workspace code\ngraphs. The same pages are the source of `landing/src/content/docs` in this\ncheckout, which is what a reader on a fork or without a network still has.\n\n## What each tool answers\n\n| the question | the tool |\n| --- | --- |\n| who calls this, what references this | `find_references` |\n| what breaks if I change it | `get_blast_radius` |\n| what does this reach outward | `trace_dependencies` |\n| who uses it from another repository | `find_cross_repo_consumers` |\n| where is it declared | `find_symbol` |\n| I don't know what it is called, what files to open | `find_by_intent` |\n| what is declared in this package | `get_file_outline` |\n| give me the code of these symbols | `get_source` |\n| everything about this one symbol | `get_symbol` |\n| what is indexed, and is the graph current | `list_repositories`, `graph_status` |\n\nEleven read-only tools, plus one consent-gated mutation (`index_project`) that a\nclient has to authorize before it can register a repository or publish a\ngeneration.\n\nEvery row that names a symbol carries its repository, path, qualified name and\nline range, so it can be opened without a second call, and every tool accepts\nthat triple in place of an opaque key.\n\n**Where it loses.** A rare name in one small repository is cheaper with `grep`,\nand indexing a small file costs more than reading it. It wins on common names,\non transitive impact, on consumers in another repository, and on proving an\nabsence. Measured over 29 questions against a 37-repository corpus\n(`benchmarks/graph-tools-comparison/results-all.json`, commit `954b9eb`,\ntokenizer `o200k_base`): `35,961` tokens for Kivgraph against `267,980` for\n`grep` plus reading, both exact on 28 of the 29, median `5.95x` per question in\nKivgraph's favour. `grep` is cheaper on 5 of those 29, all of them at full\nrecall on both sides: `T1_go_trivial` asks for a name the corpus declares\ntwice, and there `grep` costs `0.53x` what Kivgraph does.\n\nA second harness, `benchmarks/mcp-token-cost`, compares against the host's own\ntool output captured verbatim, but it runs on Kivgraph's own single repository\nof 13,222 symbols: `7.64x` on the answers themselves and `1.60x` over a whole\nsession, against a `2.41x` floor set by the source bodies both arms pay for.\n\n## Status\n\nReleased and in use. `kivgraph version` reports the published release; the\nbacklog and the acceptance gate of every phase are in [`TASKS.md`](TASKS.md).\n\n- **Languages:** Go, TypeScript, Rust, Python and Dart. Python uses the\n  bundled AST worker in fallback mode; those inferred references are\n  `CANDIDATE`, never `EXACT`. Exact Python mode uses the bundled Pyright LSP\n  adapter with an installed Pyright/BasedPyright server. Dart uses the Dart\n  Analysis Server supplied by the Dart or Flutter SDK.\n- **Semantic dependencies:** Python and Dart imports can publish a package\n  dependency when exactly one registered provider owns the requested package;\n  symbol-level cross-repository edges require an explicit provider identity.\n- **Surface:** eleven read-only tools over STDIO, plus one consent-gated\n  mutation (`index_project`). The contract is\n  [docs/protocol/mcp-surface-v3.md](docs/protocol/mcp-surface-v3.md).\n- **Storage:** LadybugDB is canonical; queries are served from an immutable\n  HotSnapshot published atomically, never from the database.\n- **Platforms:** `linux/amd64`, `darwin/arm64` and `windows/amd64`.\n- **Viewer:** `kivgraph ui` serves a read-only 3D view of the published graph.\n\n## Installation\n\n### Install the MCP with one script\n\nThe installer detects the platform, downloads the latest published MCP release\nfor it, verifies both the release archive and the bundle checksums, and\ninstalls it without requiring Go or pnpm. The release contains the Go server,\nthe pinned LadybugDB library, the TypeScript worker, the bundled Python AST\nworker, the pinned `rust-analyzer`, the grammar manifest and the web viewer,\nwhose assets are 2.3 MB of the bundle. `scripts/build-bundle.sh --mcp-only`\nproduces a bundle without the viewer for anyone who wants one. `--slim` goes\nfurther for anyone packaging an `.mcpb`: it leaves out the pinned\n`rust-analyzer` and every symbol a debugger would read, which is 46.3 MB\npackaged against 24.9 MB. It downloads nothing later, so that bundle reads\nRust only where the machine already has an analyzer on its `PATH`.\n\nPublished bundles: Linux `amd64`, macOS `arm64` and Windows `amd64`.\n\nRuntime requirements: Bash on Linux and macOS or PowerShell `5.1` or later on\nWindows, Node.js `22` or later, Python 3.10 or later when indexing Python, and\non the POSIX platforms `curl`, `tar`, and `sha256sum` or `shasum`. The bundle\ncarries its own `rust-analyzer`; indexing Rust repositories additionally needs\n`cargo` on the `PATH`, and indexing Dart needs the Dart or Flutter SDK. On\nWindows the installer also installs the Visual C++ redistributable, without\nwhich `kivgraph.exe` does not start.\n\nOn macOS the binaries are not notarized. A release downloaded with `curl` is\nnot quarantined and runs; a copy downloaded with a browser needs `xattr -dr\ncom.apple.quarantine`. See\n[docs/development/macos.md](docs/development/macos.md).\n\nInstall the latest release in one command. On Linux and macOS the same line\ncovers both, because the installer reads `uname` and picks its own archive:\n\n```bash\ncurl -fsSL https://kivgraph.dev/install.sh | bash\n```\n\nOn Windows, where `install.sh` cannot run because there is no POSIX shell:\n\n```powershell\nirm https://kivgraph.dev/install.ps1 | iex\n```\n\n`install.ps1` is a second implementation of the same pre-extraction checks, and\n`internal/release/install_parity_test.go` fails when either script grows a check\nthe other lacks. Piping it into `Invoke-Expression` turns its\n`#Requires -Version 5.1` into a comment; download it to a file and run it as one\nto keep that guard.\n\nFrom a checkout, either installer can be run directly:\n\n```bash\n./scripts/install.sh\n```\n\nTo install a specific release instead of the latest one:\n\n```bash\nKIVGRAPH_VERSION=v0.9.9 ./scripts/install.sh\n```\n\nThe script installs the bundle in `~/.local/opt/kivgraph` and puts launchers\nin `~/.local/bin`; on Windows it is `%LOCALAPPDATA%\\Programs\\kivgraph` and\n`%LOCALAPPDATA%\\Programs\\kivgraph-bin`. It never modifies a registered\nrepository, creates an index, or replaces configuration files. To use a\ndifferent location, set `KIVGRAPH_INSTALL_ROOT` and `KIVGRAPH_BIN_DIR`.\n\nAdd the launcher directory to the current shell and verify both runtimes:\n\n```bash\nexport PATH=\"$HOME/.local/bin:$PATH\"\nkivgraph version\nkivgraph-ts-worker <<'EOF'\nhello\nEOF\n```\n\nCheck for a newer release or update the installed bundle:\n\n```bash\nkivgraph update --check\nkivgraph update\n```\n\nBundle replacement is atomic, preserves the configuration and graph state,\nverifies the release and bundle checksums, and replaces the installed bundle.\nThe post-install runtime refresh may partially complete, fail, and make the\ncommand exit non-zero. It also restarts an installed supervised daemon and\nrefreshes Kivgraph-managed user hooks, skills and MCP registrations. A stale\nsupervisor returns an error and is not restarted. Missing, foreign and\nproject-scoped\nintegrations are left alone. Client-owned `serve` and `ui` processes still\nneed a restart, or `--stop`, to use the new binary.\n\nDevelopment builds use a separate prerelease channel. Install one explicitly,\nthen select that channel for later checks:\n\n```bash\nrelease=vX.Y.Z-dev.N\ncurl -fsSL \\\n  \"https://github.com/Luqueee/kivgraph/releases/download/$release/install.sh\" |\n  KIVGRAPH_VERSION=\"$release\" bash\nkivgraph update --channel dev\n```\n\nFor a prerelease binary, omitting `--channel` already follows `dev`; stable\ninstallations continue to follow the stable channel. `KIVGRAPH_UPDATE_CHANNEL`\ncan be used instead of the flag, including for the interactive update notice.\n\nTo remove the installed bundle and launchers without deleting configuration,\nrepository registrations or graph state:\n\n```bash\nuninstall_url=https://github.com/Luqueee/kivgraph/releases/latest/download/uninstall.sh\ncurl -fsSL \"$uninstall_url\" -o /tmp/kivgraph-uninstall.sh\nbash /tmp/kivgraph-uninstall.sh\n```\n\nUse `bash /tmp/kivgraph-uninstall.sh --yes` for a non-interactive removal.\nWindows users can run the corresponding `uninstall.ps1` with PowerShell.\n\nWhen `kivgraph` is invoked without a command from an interactive terminal, it\nchecks for a newer release with an 800 ms timeout and a 24-hour cache in the\nplatform cache directory (`$XDG_CACHE_HOME` on Linux and\n`$HOME/Library/Caches` on macOS), under `kivgraph/update-check.json`.\nThe optional check never blocks the command when the network is unavailable.\n\nInteractive command output uses semantic ANSI colors when the destination is a\nterminal. Set `NO_COLOR` or redirect output to keep it plain.\n\n### Configure Kivgraph and its coding agents\n\nAfter an interactive release installation, the installer asks whether it should\nrun this same guided setup. Run it later, or run it directly from a checkout:\n\n```bash\nkivgraph configure\n```\n\n`configure` opens one selector for the coding agents detected on this machine\nand installs the user-scoped MCP entry, skill and hook for every selected agent.\nIt also adds project instructions at the nearest Git root. It initializes the\nempty Kivgraph configuration when needed, but it does not register a repository\nor run an index. Repeat `--target TARGET` for scripted setup; omit it to open\nthe selector.\n\nUse `↑`/`↓` (or `j`/`k`) to move, `space` to toggle an agent, `a` to select all,\n`n` to select none, `Enter` to confirm, and `q` or `Esc` to cancel. The daemon\nis offered once after the selection; `--daemon` requires it without asking and\n`--stdio` keeps one `serve` process per client. `--dry-run` previews every\nsurface without writing.\n\nSupported MCP targets are `claude-code`, `claude-desktop`, `codex`, `opencode`,\nand `oh-my-pi`. Supported skill targets are `claude-code`, `codex`, `opencode`,\nand `oh-my-pi`; Claude Desktop has no local skill target. The standalone\ncommands use `user` by default; use `--scope project` for project-local\nconfiguration. Use `--dry-run` to inspect a plan without writing. Existing\nincompatible entries stop with an error; `--force` is required to replace or\nremove one. Existing files are written atomically with mode `0600` and receive\n`*.kivgraph.bak` backup before replacement or removal.\n\nThe pre-tool-use gate supports `claude-code`, `claude-desktop`, `codex`,\n`opencode`, and `oh-my-pi`. Oh My Pi receives a native extension under\n`~/.omp/agent/extensions/` for user scope or `.omp/extensions/` for project\nscope. The gate is fail-open when its graph query cannot be answered.\nSearches wrapped as `rtk rg ...` or `rtk proxy rg ...` are classified by their\ninner command, while RTK's own commands are left alone.\n\n### Add Kivgraph to project agent instructions\n\nAdd the Kivgraph navigation rules to the project context loaded by a coding\nagent:\n\n```bash\nkivgraph instructions install\n# The selector can install one or more coding-agent destinations.\nkivgraph instructions install --agent codex\nkivgraph instructions install --agent claude\nkivgraph instructions install --agent omp\n```\n\nWith no `--agent` or `--file`, the interactive selector lets you choose one or\nmore coding agents. `--agent codex` and `--agent opencode` create or update the\nroot `AGENTS.md`; `--agent claude` and `--agent claude-code` use the root\n`CLAUDE.md`; `--agent omp` and `--agent oh-my-pi` use the native\n`.omp/AGENTS.md`. The selector deduplicates agents that share a destination.\nThe file is placed at the nearest ancestor containing a `.git` marker, or in\nthe current directory outside a Git repository. Existing instructions are\npreserved, the managed block is idempotent, and `--dry-run` previews the\nchange. An edited Kivgraph block requires `--force` to replace. Use `--file`\nonly when an explicit filename is needed instead of an agent; supported files\nare `AGENTS.md`, `CLAUDE.md` and `.omp/AGENTS.md`. The command changes only the\nselected project file and its atomic-write backup. Use `configure` when you\nwant this project file and the compatible client integrations in one flow; the\nindividual commands remain available for explicit changes.\n\nInspect or remove a registration explicitly:\n\n```bash\nkivgraph mcp status --target claude-code --scope user\nkivgraph mcp remove --target claude-code --scope user\nkivgraph skill status --target claude-code --scope user\nkivgraph skill remove --target claude-code --scope user\nkivgraph hook status --target claude-code --scope user\nkivgraph hook remove --target claude-code --scope user\n```\n\nInitialize and publish a graph before starting the MCP server:\n\n```bash\nkivgraph init \\\n  --repository project=/absolute/path/to/project \\\n  --languages go,typescript,rust\nkivgraph doctor\nkivgraph index --full\n```\n\n`init` writes a self-contained configuration: with `--config` pointing\nelsewhere, its state, cache and registry hang off that directory, so a throwaway\nindex never touches the real one. `index --full` republishes atomically — a\nfailure at any stage leaves the previous generation serving. A server already\nrunning follows the new generation on its own.\n\nWhen you are inside one project, `kivgraph index` detects its supported\nlanguages, creates or reuses `.kivgraph/`, registers the current project as\n`project` in its local registry, and runs the same full rebuild. With neither\n`--config` nor `--repositories`, it does not alter the shared user registry;\nthose overrides intentionally select the configuration and registry to update.\nUse `kivgraph index --full` when you want the explicit registered-repositories\nworkflow; both forms preserve the full-indexing contract.\nThe command does not install language toolchains implicitly; `kivgraph doctor`\nreports any prerequisite that is missing on the host. Optional analyzers can be\nmanaged explicitly by Kivgraph:\n\n```bash\nkivgraph toolchain status\nkivgraph toolchain install pyright\nkivgraph index --full\n```\n\n`toolchain install pyright` pins and installs Pyright under Kivgraph's state,\nthen activates exact Python analysis in the selected configuration. For a\nproject-local configuration, pass `--config .kivgraph/config.yaml`. Removing\nit requires an explicit confirmation and restores the bundled Python fallback\nwhen the selected configuration uses the managed analyzer:\n\n```bash\nkivgraph toolchain remove pyright --yes\n```\n\nThe first install requires npm and network access. Later status checks and\nreusing an installed version work offline.\n\nThe command family is intentionally language-agnostic; more managed analyzers\ncan use it without making `index` mutate the host or a repository.\n\nDay to day:\n\n```bash\nkivgraph graph status      # what is published, and whether a tree has moved\nkivgraph doctor            # toolchains, storage, and the type-checking ceiling\nkivgraph ui                # read-only 3D viewer, default 0.0.0.0:7777\nkivgraph logs --follow     # what it indexed, served and answered, as it happens\nkivgraph tool-stats        # per-tool cost, calls, and failures\nkivgraph stop              # terminate this user's serve and ui, never an index\nkivgraph clean --keep-active\n```\n\n`kivgraph ui` binds a non-loopback address by default, because the graph is\nindexed where the repositories are and looked at from elsewhere; there is no\nauthentication, so it logs exactly what it exposes and `--addr` restricts it.\n\n`logs` and `tool-stats` read an append-only record in the state directory\nrather than asking a server, which is why they can answer at all: the per-tool\ncounters a `serve` keeps are minted when it starts and gone when it stops.\nReading the file also makes the answer span every server that ever ran.\n\nConfigure any MCP client to start the server over STDIO:\n\n```json\n{\n  \"mcpServers\": {\n    \"kivgraph\": {\n      \"command\": \"/home/user/.local/bin/kivgraph\",\n      \"args\": [\n        \"serve\",\n        \"--config\",\n        \"/home/user/.config/kivgraph/config.yaml\"\n      ]\n    }\n  }\n}\n```\n\n`kivgraph serve` starts before a graph exists: with no published generation it\ncompletes the handshake, publishes no query tool and puts the rebuild command in\n`instructions`. A client launches the process itself, so exiting would read as a\ncrash. It writes MCP framing exclusively to `stdout` and logs to `stderr`.\n\n## Requirements\n\n- Go 1.26 or later to build from source. The indexer type-checks with the\n  `go/types` linked into the binary, so it can only read repositories and\n  dependencies written for its own language version or older; `kivgraph doctor`\n  reports that ceiling.\n- Indexing Rust needs `cargo` and `rust-analyzer`. The release bundle carries\n  the analyzer; it does not carry a Rust toolchain.\n- Indexing TypeScript needs Node.js 22 or later for the worker.\n- Indexing Python needs Python 3.10 or later for the bundled worker. It is a\n  syntax-aware fallback and reports dynamic or unresolved names explicitly;\n  exact mode additionally requires a Pyright-compatible language server.\n- Indexing Dart needs the `dart` executable; a Flutter installation supplies\n  it. The loader uses the Analysis Server protocol and does not modify the\n  Flutter project.\n\n## What the graph carries, and what it refuses to\n\nAn edge is `EXACT` only with sufficient evidence and the right provenance. It is\nnever created from a name, a path, an alias or a single candidate, and a\nreference that cannot be resolved is published as `UNRESOLVED` with its reason,\nrepository and language rather than dropped. `graph_status` reports both, broken\ndown.\n\nThat is why some answers are absences rather than edges. With the Rust standard\nlibrary indexed, `impl Add for u32` is generated by a macro and exists in no\nsource range, so every use of it is declared `PROVIDER_DEFINITION_NOT_INDEXED`\nonce per symbol instead of becoming an edge nobody could open.\n\nThe providers Kivgraph derives from the machine — today the Rust standard\nlibrary, named `rust:1.96.1` after the toolchain — are withheld from read\nresults by default: one toolchain is around twenty thousand symbols, and a\nsearch for `Clone` would answer with `core`. `include_derived` asks for them, and\n`graph_status` breaks out what they contribute so the totals stay readable.\n\n## Development\n\n```bash\nmake build\nmake test\nmake semantic-coverage\nmake test-ladybug\n```\n\n`make test-ladybug` is the only supported way to run the tag that links the\npinned native library. Contributing conventions are in\n[AGENTS.md](AGENTS.md), which `CLAUDE.md` links to.\n\n`make semantic-coverage` is the release gate for Go, TypeScript, Python and\nDart. It validates the machine-readable matrix in\n`testdata/semantic-coverage/manifest.json`, runs the exact TypeScript, Go and\nDart suites, and requires a Pyright-compatible language server for the exact\nPython suite. A language is not considered complete when a capability has a\nfixture but no executable regression test.\n\n### Storage and graph benchmarks\n\nThe LadybugDB qualification, the synthetic corpus generator, the load and query\nbenchmarks, and the `doctor`, `rebuild`, `rollback` and `snapshot` commands are\ndocumented in\n[docs/development/storage-benchmarks.md](docs/development/storage-benchmarks.md).\nIt concludes with `ACCEPT_LADYBUGDB_WITH_LIMITS`.\n\n### The public site\n\n`landing/` carries the landing page and the user documentation. It ships in no\nrelease bundle, is verified with `make landing-check` and `make landing-build`,\nand is served on port `6767`. What it publishes, how the MCP reference was\ncaptured, and what is still open are recorded in\n[docs/development/landing-site.md](docs/development/landing-site.md).\n\n## Structure\n\n```text\ncmd/kivgraph/   Main executable.\ninternal/        Kivgraph internal packages.\nts-worker/        TypeScript worker.\nweb/              Graph viewer served by `kivgraph ui`.\nlanding/          Landing page and documentation site (not part of any release).\ntestdata/         Test fixtures and corpora.\nbenchmarks/       Benchmark results.\ndocs/             Documentation and ADRs.\nscripts/          Auxiliary automation.\n```\n\n## License\n\nKivgraph is distributed under the [Apache License 2.0](LICENSE).\n\n## Third-party licenses\n\nNotices and licenses for dependencies distributed with Kivgraph are recorded in [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md). The list is updated whenever a dependency is added to the distributable product.\n",
  "bytes": 21681,
  "sha": "cea7d93b0cbd34f4309ec6f3b3c769822d15d3f6a423792031fd19874ca0051d",
  "repo_slug": "luqueee/kivgraph",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_luqueee_kivgraph_844ab033/readme"
}