GitNexus: turning a repository into a knowledge graph your AI agent can query over MCP

What GitNexus solves, and for whom

An agent editing a repository works from whatever text it has loaded. It sees the file it was pointed at and maybe a few neighbours. It does not see that a function is called from six places, that a module sits in a cycle, or that the change it is about to make breaks a chain three hops away. GitNexus exists to close that gap. The README describes it as a client-side knowledge graph creator and, in the CLI framing, as something that gives Cursor, Claude Code, Antigravity and Codex a deep architectural view of a codebase so they stop missing dependencies and shipping blind edits.

The target user is not someone browsing a repository for the first time. It is someone who already has an agent in the loop and wants that agent to reason over structure instead of text similarity. The README makes the distinction explicit against DeepWiki: DeepWiki helps you understand code, GitNexus is meant to let you analyze it, because a graph tracks relationships rather than descriptions. That is a defensible line. Retrieval over chunks tells you which passages look like your question. A call graph tells you what actually invokes what, which is a different and often more useful answer.

How the graph gets built and served

There are two halves, and they are separable. The indexing half parses a repository and produces a graph: every dependency, call chain, cluster and execution flow, in the README's wording. The serving half exposes that graph through MCP tools so an agent can query it during a session.

The repository layout supports this reading. The monorepo carries gitnexus (the CLI and server), gitnexus-web (the browser UI), gitnexus-shared, and separate integration directories for Claude and Cursor (gitnexus-claude-plugin, gitnexus-cursor-integration). There is a Dockerfile.cli and a Dockerfile.web, so the two halves ship as distinct images, and docker-compose.yaml runs them as two services. The server listens on 4747 and the web container on 4173.

The parse itself relies on tree-sitter grammars. Four of them, for Dart, Proto, Swift and Kotlin, are vendored under the repository rather than pulled as prebuilt binaries, and the README explains why: upstream ships source only for Kotlin, so GitNexus cross-builds the platform prebuilds itself through a GitHub Actions workflow named build-tree-sitter-prebuilds. That is an unusual amount of build machinery to carry for four languages, and it is the kind of decision that pays off in install reliability and costs in maintenance surface.

Embeddings are optional and live in a separate runtime directory, ~/.gitnexus/embedding-runtime, overridable with GITNEXUS_EMBEDDING_RUNTIME_DIR. The README notes the on-demand prefix needs Node with module.registerHooks, which means 22.15 or newer on the 22.x line and 23.5 or newer on 23.x.

Installing GitNexus and running your first analyze

The README's quick start is two commands. Run the first from the repository root. It indexes the codebase, installs agent skills, registers Claude Code hooks, and writes AGENTS.md and CLAUDE.md context files.

npx gitnexus analyze

The second command is a one-time editor connection step. The README says it auto-detects Claude Code, Cursor, Codex and similar tools, and writes the MCP configuration so the agent can reach the graph.

npx gitnexus setup

If npx crashes during install on npm 11.x with Cannot destructure property 'package' of 'node.target', the README attributes this to an npm/arborist bug that fires before GitNexus runs, and points at issue #1939. The documented workaround is pnpm, which builds the native dependencies explicitly.

pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter dlx gitnexus@latest analyze

The README also recommends a global install before setup, because an npx-based MCP config can exceed Claude Code's MCP_TIMEOUT default of roughly 30 seconds on a cold cache. A global install lets setup write an absolute-path config that skips npx entirely.

npm i -g gitnexus
gitnexus setup

If you have no C++ toolchain, set GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 before a global install. The README is precise about the value: strict =1 only, since any other value falls through to the rebuild. Dart, Proto, Swift and Kotlin stop being parsed, and the install finishes in seconds without python3, make or g++. That is a reasonable trade if you are not working in those languages.

export GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1
npm install -g gitnexus

For a container deployment, the README gives a Render blueprint that creates two services: gitnexus-server as a private service with a persistent disk, and gitnexus-web as the public one, reverse-proxying /api/* to the server. The README states the blueprint's defaults run about $35 per month, broken into $25 for the server's standard instance, $7 for the web service's starter instance, and $2.50 for the 10 GB disk. Deployment generates an access token; you copy GITNEXUS_SERVE_AUTH_TOKEN from the web service's Environment tab and paste it into the UI prompt. The browser keeps it in sessionStorage, so a new tab asks again.

The token is the whole security model on a hosted deploy

This is the part worth reading twice. The README is candid that the Render proxy strips Origin before forwarding, so the server's CSRF guard does nothing for proxied traffic, and the proxy passes Origin-less requests through by design. The token becomes the only control, not a second layer behind the guard. Anyone holding it can read every indexed repo. That is a single-secret design, and a leaked token is not a partial exposure.

Indexing is memory-bound. The README says that if gitnexus-server runs out of memory on a large repository, you raise its plan, which sets available RAM: standard is 2 GB, pro is 4 GB. Raise sizeGB only if the disk fills with clones and indexes. There is no documented streaming or incremental mode for the memory ceiling itself, so a big monorepo on a small instance fails rather than degrades.

Note also what the compose file deliberately avoids. It does not bind-mount the repository root, because that would expose .git, .env and CI secrets to the container. It mounts a ./workspace sibling read-only instead, overridable with WORKSPACE_DIR. That is a sensible default and a mild inconvenience: repos you want indexed have to be placed or mounted where the server can see them.

Where GitNexus is the wrong tool

The licence is the first constraint. The repository reports NOASSERTION, and the README links to the PolyForm Noncommercial License 1.0.0. Whatever the exact file says, the linked licence is noncommercial, which means this is not an OSI-approved permissive dependency you can drop into a commercial product without reading the terms. There is an Enterprise offering described as SaaS and self-hosted at akonlabs.com, which suggests commercial use runs through a separate arrangement. Treat that as a question for your own review, not something this article can settle.

Second, the install path has sharp edges that the README documents rather than hides. The npm 11 crash, the cold-cache MCP timeout, the missing C++ toolchain, and the proxy problem where onnxruntime-node's postinstall downloads CUDA binaries from api.nuget.org while ignoring HTTP_PROXY and HTTPS_PROXY (issue #2370). The README notes the embedding stack is optional so a failed download no longer breaks the install, and that it self-heals on the first gitnexus analyze --embeddings or gitnexus embeddings install. Self-healing is good. Needing it on a corporate network is friction.

Third, scale. If your repository is a few thousand lines, the graph is more machinery than the question deserves. The value shows up when a codebase is large enough that no agent can hold its structure in context.

Finally, the release cadence deserves a look. The most recent releases listed are v1.6.11-rc.1, v1.6.11-rc.2 and v1.6.11-rc.3, all release candidates, with the last push on 2026-08-29. If you pin to stable tags, check what the latest non-RC version actually is before you assume the README's commands describe it.

How it differs from Graphify and code-review-graph

People search for GitNexus against Graphify and code-review-graph, and the honest answer is that the README does not describe either competitor's internals, so any detailed comparison would be invented. What can be said is structural, from what GitNexus itself claims.

GitNexus produces a knowledge graph and serves it to an agent at edit time through MCP. That places it upstream of review. A tool oriented around reviewing a diff answers a question about a change that already exists; GitNexus is aimed at the moment before the change, when the agent is deciding what to write. That is the distinction the README draws when it says the CLI and MCP make an agent reliable by giving it an architectural view so it stops breaking call chains.

The second difference is deployment shape. GitNexus ships a browser UI and a server, plus a two-container compose file and a Render blueprint. A tool that runs purely as a local CLI has a smaller operational footprint. If you want something you invoke and forget, the two-service topology is overhead you are choosing to carry. If you want a shared index that a team can point at, that topology is the point.

Maintenance cost and what the licence means in practice

The last push was on 2026-08-29, so the project is being worked on, but the visible release line is release candidates. Pin a version, read the CHANGELOG before upgrading, and do not assume an rc is a stable target for a team.

The upgrade surface is larger than a typical CLI. A global install pulls native dependencies, tree-sitter grammars, and an optional embedding stack that downloads its own runtime on first use into ~/.gitnexus/embedding-runtime. Node version matters: the on-demand embedding prefix needs module.registerHooks, meaning 22.15 or newer on 22.x and 23.5 or newer on 23.x. The README offers ONNXRUNTIME_NODE_INSTALL=skip npm install -g gitnexus as the path for older Node, which keeps the stack inside the install instead.

On licensing, the repository reports NOASSERTION and the README links to PolyForm Noncommercial 1.0.0. That combination means you should read the LICENSE file in the repository rather than the badge, because the two are not the same statement. Noncommercial terms typically restrict use in revenue-generating contexts, and the existence of a separate Enterprise offering implies the maintainers expect commercial users to come through it. This is a question for your own legal review, and the README does not answer it.

Editorial conclusion

Adopt GitNexus if you already drive an agent inside Claude Code, Cursor, Codex or a similar editor and you want that agent to see call chains and dependencies rather than the handful of files it happened to open. Skip it if you need a permissively licensed dependency in a commercial product, or if your work is a small script where a full index is more machinery than the question deserves. Before committing, read LICENSE and decide whether the noncommercial terms fit, then run npx gitnexus analyze on one repository and inspect the AGENTS.md and CLAUDE.md files it writes, since those are the artifacts your agent will actually read.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes