# GitNexus: what analyze and setup actually do, and the four install traps in between

> GitNexus indexes a repository into a knowledge graph and hands it to AI coding agents over MCP. The interesting part for a reader is not the graph, it is the four documented failure points between installing the CLI and having an agent that can query your code.

**abhigyanpatwari/GitNexus** — GitNexus: The Zero-Server Code Intelligence Engine -       GitNexus is a client-side knowledge graph creator that runs entirely in your browser. Drop in a git repository (Github, Gitlab, Azure, Local) or ZIP file, and get an interactive knowledge graph with a built in Graph RAG Agent. Perfect for code exploration

- Repository: https://github.com/abhigyanpatwari/GitNexus
- Website: https://gitnexus.vercel.app
- Stars: 47,648 · Forks: 5,178
- Language: TypeScript
- License: NOASSERTION
- Published: 2026-08-17 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/abhigyanpatwari-gitnexus

## analyze writes four things into your repo, and setup is what connects an agent

The Quick Start is two commands:

```bash
# 1. Index your repo (run from repo root)
npx gitnexus analyze

# 2. Connect your editors (one-time, auto-detects Claude Code, Cursor, Codex, …)
npx gitnexus setup
```

`analyze` is the one that does the work, and it does more than parse: it indexes the codebase, installs agent skills, registers Claude Code hooks, and creates `AGENTS.md` and `CLAUDE.md` context files. `setup` writes the MCP config so an agent can reach the graph at all. That split is the first thing to understand, because a repository can be fully indexed and still be invisible to your editor if you never run `setup`.

The consequence for a reader is that `analyze` is not a read only operation. It adds files at your repo root and registers hooks with your editor, so it belongs in the same review as any other change to your working tree. The top-level entries show the project keeping those artifacts under version control in its own repository: `AGENTS.md`, `CLAUDE.md`, `.mcp.json`, a `.claude/` directory, a `.cursor/` directory, `.cursorrules` and `.windsurfrules`. The command that writes them is the same command the project runs on itself.

## npm 11 can crash during install, before GitNexus ever runs

The first documented failure point happens before any of your code is read. On npm 11.x, `npx` can crash during install with `Cannot destructure property 'package' of 'node.target'`, which the project attributes to an npm and arborist bug rather than to itself. The message names npm internals and says nothing about your repository, so the natural reaction, retrying with a different flag, wastes time.

The documented workaround is pnpm, which builds the native dependencies explicitly:

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

The alternative is to stop using `npx` for the install and keep a global copy instead, `npm install -g gitnexus@latest`, then run `gitnexus analyze`. The project files this under issue 1939, which is where to look when you hit the crash yourself. What this section cannot tell you is which package manager your CI image ships, so the practical move is to check that before the first run rather than after.

## A global install writes an absolute path config and steps around MCP_TIMEOUT

The second failure point shows up later, when the agent starts. On a cold cache, an `npx` based MCP install can exceed the `MCP_TIMEOUT` default in Claude Code, which the project puts at roughly 30 seconds. The symptom is an editor that reports the GitNexus tool as missing even though the index exists, and the fix is an installation choice rather than a larger timeout.

The fix is to install the package globally, `npm i -g gitnexus`, before running `gitnexus setup`. Doing that makes `setup` write an MCP config containing an absolute path, so the config no longer shells out through `npx` on every launch. Two consequences follow. The MCP server start no longer depends on a warm npm cache, which is what removes the timeout risk. And `setup` is described as one time and as auto detecting Claude Code, Cursor and Codex, so re running it after switching editors is the intended way to point a new tool at the same index.

What this does not do is make the index fast. A large repository still takes time to analyze, and the order of the two commands matters as much as the order of the two installations.

## GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 trades four languages for a toolchain free install

The third escape hatch is about build prerequisites rather than package managers. Without it, the install tries to materialize and build vendored tree-sitter grammars, which needs `python3`, `make` and `g++` on the machine. Setting `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1` before `npm install -g gitnexus` skips that step, and the install completes in seconds with no C++ toolchain at all.

The cost is named explicitly: `tree-sitter-dart`, `tree-sitter-proto`, `tree-sitter-swift` and `tree-sitter-kotlin` will not be parsed, so those four languages are missing from the graph your agent queries. The flag is also a sentinel rather than a boolean, because the project states that a strict `=1` is required and any other value falls through to the rebuild. Typing `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=true` therefore gets you the slow path and the original error.

A narrower escape exists for one of the four. Kotlin is vendored under `gitnexus/vendor/tree-sitter-kotlin`, GitNexus cross builds the platform prebuilds itself, and `node-gyp-build` selects the right `.node` at require time, so Kotlin needs no C or C++ toolchain either. If no prebuild matches your platform and architecture, only `.kt` and `.kts` parsing is unavailable and the rest of the tool is unaffected.

## Embeddings are opt-in, land in a home directory, and carry a Node floor

A default install does not give you local embeddings. It does not fetch `@huggingface/transformers` or `onnxruntime-node` at all, and the runtime you eventually need is written into `~/.gitnexus/embedding-runtime` through your own npm registry configuration. You ask for it in one of two ways:

```bash
gitnexus embeddings install
gitnexus analyze --embeddings
```

The second form auto heals, so a run that finds a missing runtime fetches it rather than failing. Two extra details travel with that path. CUDA GPU binaries still come from NuGet through a `--cuda` flag, tracked as issue 2370, so a GPU machine is not a pure npm install. And the prefix needs a Node with `module.registerHooks`, which the project pins as 22.15 or later on the 22.x line and 23.5 or later on the 23.x line.

The consequence for a reader is that an index built without the runtime has no vector side to it, and an agent asking a semantic question over that index gets a graph answer or nothing. The project also warns that a leftover 1.6.12 package-first tree stays residual until a clean reinstall, because `--force` only refreshes prefix overrides.

## The hosted deploy has one control, and the CSRF guard is bypassed by design

The Render Blueprint creates two services. `gitnexus-server` runs `gitnexus serve` as a private service with no public URL, reachable only over Render's private network, with a persistent disk for indexes and cloned repos. `gitnexus-web` is the public one, serves the UI and reverse proxies `/api/*` so the browser talks to a single origin. At the Blueprint defaults that is about $35 a month, $25 for the server's `standard` instance, $7 for the web service's `starter` instance and $2.50 for the 10 GB disk.

The security arrangement is stated bluntly. Every `/api/*` request carries `GITNEXUS_SERVE_AUTH_TOKEN` as a header and the proxy answers `401` without it, the browser keeps it in `sessionStorage` so a new tab asks again, and rotating it means editing the environment variable and redeploying. The proxy strips `Origin` before forwarding, so the server's CSRF guard does nothing for proxied traffic and passes `Origin` less requests through by design. The token is the only control, and anyone holding it can read every indexed repo. SECURITY.md has a section on hosted deploys on Render for the rest of it.

The practical limit is memory. Indexing is memory bound, `standard` is 2 GB and `pro` is 4 GB, and `sizeGB` is the disk knob to raise only when clones and indexes fill the volume.

## docker-compose mounts ./workspace read-only, and .env.example points one level up

The Compose file runs the same two images locally. `gitnexus-server` publishes `${SERVER_HOST_PORT:-4747}:4747`, mounts a named volume at `/data/gitnexus` for the registry, indexes and cloned repos, and mounts `${WORKSPACE_DIR:-./workspace}` at `/workspace:ro` so that `gitnexus index <path>` can see repos already on disk. A healthcheck curls `http://localhost:4747/api/health` every 30 seconds with a 5 second timeout, 3 retries and a 15 second start period. `gitnexus-web` publishes `${WEB_HOST_PORT:-4173}:4173` and takes `GITNEXUS_BACKEND_URL` for setups where the two are not on one host.

The interesting part is what the file says about the workspace default. The comment explains that compose creates an empty `./workspace/` sibling on first start and that it intentionally does not bind mount the repo root, because that would expose `.git`, `.env` and CI secrets to the container. Read `.env.example` and you find `WORKSPACE_DIR=./` in it, one level above that sibling. The consequences of getting this wrong are concrete: a read-only mount is still a mount, so pointing `WORKSPACE_DIR` at a working tree hands the container your git history and any env file inside it, and the container runs as the image does, not as you.

## The monorepo re-indexes itself with embeddings and skills, on demand

The root package.json is private and named `gitnexus-monorepo`, and two of its scripts are the project indexing itself. `gitnexus:refresh` is `gitnexus analyze --embeddings --skills`, and `gitnexus:full` is `gitnexus analyze --force --embeddings --skills`, the same command with `--force` added. The tree holds separate packages for the CLI, the web UI, shared code, test setup, a Claude plugin, a Cursor integration, a Factory plugin and a `pr-swarm-review/` directory, which is what a monorepo of this shape costs to keep honest.

The commit gate is as short as the scripts are. `prepare` runs husky, and lint-staged runs `eslint --fix` plus `prettier --write` on TypeScript and React files, and `prettier --write` on js, jsx, mjs, json, css and yaml. Tool versions are pinned in devDependencies, from eslint at 9.39.4 and typescript at 5.9.3 to prettier at 3.8.0 with prettier-plugin-tailwindcss at 0.7.0. Alongside them sit `eval/`, `eslint-rules/`, `TESTING.md`, `DoD.md`, `RUNBOOK.md`, `ARCHITECTURE.md`, `GUARDRAILS.md` and `MIGRATION.md`.

For a reader, the release cadence is the part to note: the last three tags are release candidates, v1.6.13-rc.55, rc.56 and rc.57, all on 2026-09-29. A checkout of this project is a project in motion, and its own scripts assume you can rebuild the index whenever the code moves.

## Conclusion

GitNexus fits a team that has already decided an agent needs architectural context rather than file contents, and that is willing to own a local index. It is a poor fit if you need a permissively licensed tool, since the license recorded for the repository is not a standard open source grant and the badge points at PolyForm Noncommercial 1.0.0. Before you rely on it, read LICENSE yourself, check that your Node version clears the module.registerHooks floor if you turn on embeddings, and decide up front whether your repositories may sit in a hosted index that a single token guards.

## FAQ

### What is GitNexus?

A client-side knowledge graph creator that runs entirely in your browser. You drop in a git repository from Github, Gitlab, Azure or a local path, or a ZIP file, and get an interactive knowledge graph with a built-in Graph RAG agent, plus a CLI and MCP path for editors.

### How do I install GitNexus?

Run `npx gitnexus analyze` from the repo root, then `npx gitnexus setup` to write the MCP config. On npm 11.x the npx install can crash with `Cannot destructure property 'package' of 'node.target'`, and the documented fallback is pnpm or a global `npm install -g gitnexus@latest`.

### What does gitnexus do?

It indexes a codebase into a knowledge graph covering every dependency, call chain, cluster and execution flow, then exposes that graph through MCP tools so agents can query it. `analyze` also installs agent skills, registers Claude Code hooks, and creates AGENTS.md and CLAUDE.md.

### What is gitnexus used for?

For teams whose coding agents miss dependencies and break call chains. The CLI and MCP path gives editors such as Cursor, Claude Code, Antigravity and Codex an architectural view of a repository, and the Web UI is a graph explorer with chat that runs in the browser.

### is gitnexus open source

The license recorded for the repository is not a standard open source grant, and the README carries a PolyForm Noncommercial 1.0.0 badge. A LICENSE file sits at the top level of the tree, so read it yourself before assuming the terms you need.

### Is GitNexus safe to host?

On the Render deploy the access token is the only control: the proxy strips Origin before forwarding, so the server's CSRF guard does nothing for proxied traffic, and anyone holding `GITNEXUS_SERVE_AUTH_TOKEN` can read every indexed repo. The README points at the hosted deploys section of SECURITY.md.

## Sources

- [Official documentation](https://gitnexus.vercel.app)
- [Official README](https://github.com/abhigyanpatwari/GitNexus#readme)
- [Project repository](https://github.com/abhigyanpatwari/GitNexus)
- [Release notes](https://github.com/abhigyanpatwari/GitNexus/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/abhigyanpatwari-gitnexus