Installation

Detailed installation instructions, system requirements, and verification steps for GitNexus.

System requirements

Before installing GitNexus, ensure your system meets these requirements:

Requirement	Version
Node.js	>= 18.0.0
Git	Any recent version
Operating System	Linux, macOS, or Windows

GitNexus uses native bindings for Tree-sitter and KuzuDB. These are pre-compiled for most platforms and installed automatically.

Installation methods

Use without installing (recommended)

The fastest way to use GitNexus is with npx — no installation required:

npx gitnexus analyze

This downloads the latest version, runs the indexing, and exits. Perfect for trying GitNexus or one-off analysis.

Global installation

For regular use, install GitNexus globally:

npm install -g gitnexus

Now you can run gitnexus commands from anywhere:

gitnexus analyze
gitnexus setup
gitnexus list

Local installation

You can also install GitNexus as a dev dependency in a specific project:

npm install --save-dev gitnexus

Then use it via npm scripts:

package.json

{
  "scripts": {
    "index": "gitnexus analyze",
    "index:force": "gitnexus analyze --force"
  }
}

Local installation means each project gets its own copy of GitNexus. This is useful for CI/CD but not recommended for general development (use global install instead).

Verify installation

Check that GitNexus is installed correctly:

gitnexus --version

You should see the current version number (e.g., 1.3.6).

Supported languages

GitNexus supports parsing and indexing for these languages:

TypeScript

Full support for TS syntax, imports, and type resolution.

JavaScript

ES6+, CommonJS, and ESM.

Python

Classes, functions, imports.

Java

Classes, methods, inheritance.

C

Functions, headers.

C++

Classes, templates, inheritance.

C#

Classes, methods, namespaces.

Go

Packages, functions, interfaces.

Rust

Modules, functions, traits, impls.

PHP

Classes, functions, namespaces.

Swift

Classes, protocols, extensions.

Language support is based on Tree-sitter grammars. If you need support for additional languages, open an issue on GitHub.

Post-install setup

1. Index your first repository

Navigate to any git repository and run:

cd ~/projects/my-app
gitnexus analyze

This creates a .gitnexus/ directory with the knowledge graph. The directory is automatically added to .gitignore.

1. Scanning files

   GitNexus walks the file tree and identifies source files.

2. Parsing code

   Tree-sitter extracts functions, classes, methods, and interfaces.

3. Resolving imports

   Language-aware import resolution maps dependencies.

4. Tracing calls

   Call chain detection builds the execution graph.

5. Detecting communities

   Leiden algorithm groups related symbols into functional clusters.

6. Detecting processes

   Execution flows traced from entry points through call chains.

7. Creating indexes

   Full-text search and vector embeddings for hybrid search.

2. Configure MCP for your editor

Run the auto-setup:

gitnexus setup

This detects your installed editors and writes the correct global MCP config.

Supported editors:

• Claude Code: Full support (MCP + skills + hooks)
• Cursor: MCP + skills
• Windsurf: MCP only
• OpenCode: MCP + skills

See the quickstart guide for manual configuration.

3. Verify MCP connection

Restart your editor, then ask your AI agent:

List all indexed repositories

You should see your repo with stats like:

my-app
  Path: /Users/you/projects/my-app
  Symbols: 1,348
  Relationships: 3,469
  Processes: 104
  Last indexed: 2 minutes ago

CLI commands reference

Here are all the commands you’ll use:

Core commands

# Index a repository (or update stale index)
gitnexus analyze

# Force full re-index
gitnexus analyze --force

# Skip embedding generation (faster, but no semantic search)
gitnexus analyze --skip-embeddings

# Configure MCP for your editors (one-time)
gitnexus setup

# Start MCP server (stdio) — serves all indexed repos
gitnexus mcp

Management commands

# List all indexed repositories
gitnexus list

# Show index status for current repo
gitnexus status

# Delete index for current repo
gitnexus clean

# Delete all indexes (requires --force)
gitnexus clean --all --force

Advanced commands

# Start local HTTP server for web UI connection
gitnexus serve

# Generate repository wiki from knowledge graph
gitnexus wiki

# Wiki with custom LLM model
gitnexus wiki --model gpt-4o

# Wiki with custom LLM API base URL
gitnexus wiki --base-url https://api.anthropic.com/v1

The serve command starts a local HTTP server that the web UI can connect to. This lets you browse all your CLI-indexed repos in the browser without re-uploading or re-indexing.

Storage and privacy

Where data is stored

GitNexus stores data in two places:

1. Per-repo index: .gitnexus/ inside each indexed repository

   • Knowledge graph database (KuzuDB)
   • Search indexes (BM25 + embeddings)
   • Metadata (last commit, indexed date)
   • Automatically added to .gitignore

2. Global registry: ~/.gitnexus/registry.json

   • List of all indexed repos
   • Paths and metadata only (no code)
   • Used by MCP server to discover repos

Privacy guarantees

No network calls

GitNexus CLI runs 100% locally. No telemetry, no analytics, no phone-home.

No cloud uploads

Your code stays on your machine. Nothing is uploaded to any server.

Gitignored by default

The .gitnexus/ directory is automatically added to .gitignore.

Open source

Audit the code yourself: github.com/abhigyanpatwari/GitNexus

Troubleshooting

”Not inside a git repository”

GitNexus only indexes git repositories. If you see this error:

cd /path/to/repo
git init  # if not already a git repo
gitnexus analyze

“Module did not self-register”

This error means native bindings (Tree-sitter or KuzuDB) failed to load. Usually caused by Node version mismatch.

Fix:

1. Check Node version: node --version (must be >= 18)
2. Reinstall GitNexus: npm install -g gitnexus
3. If still failing, open an issue with your Node version and OS

Large repos / out of memory

GitNexus automatically increases heap size to 8GB for large repos. If you still hit memory limits:

# Skip embeddings to reduce memory usage
gitnexus analyze --skip-embeddings

Note: This disables semantic search, but all other features work.

Stale index warning

If you see “Index is stale” warnings from MCP resources:

cd /path/to/repo
gitnexus analyze  # re-index to pick up new commits

GitNexus automatically detects when the repo has new commits and needs re-indexing.

Next steps

Quickstart

Get up and running in under 2 minutes.

MCP integration

Learn about tools, resources, and prompts.

Web UI

Try the browser-based graph explorer.

CLI reference

Full CLI command documentation.