GitNexus guide: indexing a repository into a code graph for MCP agents, the CLI and a web explorer

analyze writes into your repository unless you pass --index-only

The quick start is two commands, run from the repository root, on Node.js 22.18+ within the 22.x line or 24.11+:

# Run from your repository root
npx gitnexus analyze

# Connect your editors once
npx gitnexus setup

The first command does more than index. analyze builds the index, installs agent skills, registers Claude Code hooks and writes AGENTS.md and CLAUDE.md context files. setup then configures MCP for your editors. The consequence: running analyze on a shared repository leaves new and changed files in the working tree that teammates will see in the next diff. If you only want the graph, use the flag that skips those integration files:

gitnexus analyze --index-only

For repeated use, install the CLI globally:

npm install -g gitnexus

Linux and Windows need native dependencies, listed under platform requirements in gitnexus/README.md, with a troubleshooting section for failed installs.

Six MCP tools answer graph questions for the agent

Once an editor is connected, the agent gets a set of tools with narrow jobs. query finds code and related execution flows. context inspects a symbol's callers and dependencies. impact checks what a change could affect. trace follows a path between two symbols. detect_changes reviews the impact of a Git diff. rename previews and applies a semantic rename. In practice you ask the agent questions like "What calls this function?" or "What would this change affect?" and it reaches for these tools. The answers come from the graph, not from the model reading files, so they are only as complete as the index. GitNexus says so itself: resolution depends on language support and available evidence, and you should check reported ambiguity, index freshness and coverage limits before trusting an answer. A stale index will report impact for code that no longer exists.

Editor detection covers eight clients and leaves Windsurf to you

gitnexus setup detects Claude Code, Cursor, Codex, Antigravity, Factory Droid, OpenCode, CodeBuddy and Qoder. Windsurf is the exception that needs manual MCP configuration, covered in docs/editor-setup.md along with hooks and plugin installation. To limit setup to particular editors, pass them as a list:

gitnexus setup -c cursor,codex

Running several agents at once changes the advice. Instead of each client starting its own stdio server, run one shared HTTP server and point every client at it:

gitnexus mcp --http --port 3111

Clients then connect to http://127.0.0.1:3111/mcp. The repository also ships plugin folders for Claude, Cursor and Factory, under gitnexus-claude-plugin, gitnexus-cursor-integration and gitnexus-factory-plugin.

The index goes stale unless you refresh or watch

The graph is a snapshot of the repository at the time you ran analyze. The everyday commands are about keeping it current and inspecting it:

gitnexus analyze                 # Refresh the current repository's index
gitnexus analyze --watch         # Reindex as local files change
gitnexus query "authentication"  # Search the graph
gitnexus impact UserService --direction upstream
gitnexus status                  # Check index freshness
gitnexus list                    # List indexed repositories
gitnexus serve                   # Serve indexed repositories to the web UI

If you skip the refresh after a large merge, impact and context answers describe the old code, and the agent will act on them with full confidence. Use --watch during active work, or run status before relying on an impact report. The monorepo's own package.json wraps heavier runs: gitnexus:refresh runs analyze with --embeddings --skills, and gitnexus:full adds --force.

Browser UI and optional local backend

The project documents a browser-based UI at gitnexus.vercel.app that runs client-side, as well as an optional local backend mode. Run gitnexus serve to let the UI connect to locally indexed repositories and use features such as AI chat without re-uploading or re-indexing them. Indexing with the CLI runs locally. Optional remote embeddings, wiki generation and AI chat can involve configured providers; review their data handling policies before sending sensitive code. Read SECURITY.md and the deployment authentication notes before exposing an index to other users.

The Docker template mounts the directory the compose file warns against

docker-compose.yaml runs two containers. gitnexus-server listens on 4747, keeps the registry, indexes and cloned repositories in a gitnexus-data volume, and exposes a health check at http://localhost:4747/api/health. gitnexus-web serves the UI on 4173 and reaches the API through GITNEXUS_BACKEND_URL, which defaults to http://localhost:4747 and can be set to / behind a reverse proxy on the same origin. Images come from GHCR or Docker Hub (akonlabs/gitnexus), signed with Cosign keyless on every push from main and every version tag. One detail needs care. The compose file defaults WORKSPACE_DIR to an empty ./workspace folder and explains that it deliberately avoids mounting the repo root, which would expose .git, .env and CI secrets to the container. The .env.example file sets WORKSPACE_DIR=./ instead. Copy that file unchanged and the mount points at the current directory, read-only but still visible to the server. Set it to the folder holding the repositories you mean to index.

Language coverage is per construct, across 18 providers

Registered providers exist for C, C++, C#, COBOL, Dart, Go, Java, JavaScript, Kotlin, Objective-C, PHP, Python, Ruby, Rust, Swift, TypeScript, Vue and Zig. A provider being registered does not mean every construct in that language resolves. Support varies by construct, and the language inventories in docs/languages/README.md record measured behavior, exclusions and remaining gaps. For a reader with a mixed codebase the consequence is uneven answers: impact analysis can be thorough in one service and thin in another, and the tool will not always flag the difference unless it reports ambiguity. Check the inventory for your main language before relying on rename across a large codebase. The ARCHITECTURE.md and type-resolution documents explain how the resolution layers work.

A noncommercial license and a stream of release candidates

GitHub reports the license as NOASSERTION, and the license badge in the README links to the PolyForm Noncommercial License 1.0.0. That puts commercial use outside the plain terms; a company planning to run GitNexus on product code should read the LICENSE file before installing it. The project is under active development, with the last push on 2 November 2026. Its tagged releases are release candidates: v1.6.13-rc.197 on 2 November 2026, then rc.198 and rc.199 both on 3 November 2026. Expect behavior to shift between installs, and note that npx gitnexus fetches whatever is current, so pin a version with the global install if your team needs repeatable results. CHANGELOG.md and MIGRATION.md are the files to check on upgrade.

Editorial conclusion

GitNexus suits developers who already work with an MCP coding agent such as Claude Code, Cursor or Codex and want it to answer caller, impact and rename questions from a local index instead of grepping. It is a poor fit for commercial teams that cannot accept a noncommercial license, and for anyone who does not want a tool writing AGENTS.md, CLAUDE.md and hooks into the repository. Before adopting it, read the LICENSE file, check the language inventory for your stack, and start with gitnexus analyze --index-only.

Frequently asked questions

Official sources

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