Quickstart

Get GitNexus up and running in minutes

Get GitNexus indexing your codebase and connected to your AI editor in under 5 minutes.

Fast path

1. Index your repository

   Run from your repository root:

   npx gitnexus analyze
   

   This command:

   • Indexes your codebase into a knowledge graph
   • Installs agent skills to .claude/skills/
   • Registers Claude Code hooks
   • Creates AGENTS.md / CLAUDE.md context files
   • Adds the repo to ~/.gitnexus/registry.json
2. Configure your editor

   Run the one-time setup:

   npx gitnexus setup
   

   This auto-detects your editors and writes the correct MCP configuration.

3. Restart your editor

   Restart your AI coding assistant to load the MCP server and skills.

That’s it! Your agent now has deep codebase awareness through GitNexus.

What your agent gets

7 MCP Tools

Tool	What It Does
list_repos	Discover all indexed repositories
query	Process-grouped hybrid search (BM25 + semantic + RRF)
context	360-degree symbol view — categorized refs, process participation
impact	Blast radius analysis with depth grouping and confidence
detect_changes	Git-diff impact — maps changed lines to affected processes
rename	Multi-file coordinated rename with graph + text search
cypher	Raw Cypher graph queries

6 Resource Types

Resource	Purpose
gitnexus://repos	List all indexed repositories
gitnexus://repo/{name}/context	Codebase stats and staleness check
gitnexus://repo/{name}/clusters	Functional clusters with cohesion scores
gitnexus://repo/{name}/cluster/{name}	Cluster members and details
gitnexus://repo/{name}/processes	All execution flows
gitnexus://repo/{name}/process/{name}	Full process trace with steps

4 Agent Skills

Automatically installed to .claude/skills/gitnexus/:

• Exploring — Navigate unfamiliar code using the knowledge graph
• Debugging — Trace bugs through call chains
• Impact Analysis — Analyze blast radius before changes
• Refactoring — Plan safe refactors using dependency mapping

Example: Query tool

Ask your agent to search for authentication-related code:

// Agent calls:
query({
  query: "authentication middleware",
  context: "user login flow",
  limit: 3
})

Response shows process-grouped results:

{
  "processes": [
    {
      "summary": "LoginFlow",
      "priority": 0.042,
      "symbol_count": 4,
      "process_type": "cross_community",
      "step_count": 7
    }
  ],
  "process_symbols": [
    {
      "name": "validateUser",
      "type": "Function",
      "filePath": "src/auth/validate.ts",
      "process_id": "proc_login",
      "step_index": 2
    }
  ],
  "definitions": [
    {
      "name": "AuthConfig",
      "type": "Interface",
      "filePath": "src/types/auth.ts"
    }
  ]
}

Example: Impact tool

Check what breaks if you change a function:

// Agent calls:
impact({
  target: "UserService",
  direction: "upstream",
  minConfidence: 0.8
})

Response shows blast radius:

TARGET: Class UserService (src/services/user.ts)

UPSTREAM (what depends on this):
  Depth 1 (WILL BREAK):
    handleLogin [CALLS 90%] -> src/api/auth.ts:45
    handleRegister [CALLS 90%] -> src/api/auth.ts:78
    UserController [CALLS 85%] -> src/controllers/user.ts:12
  Depth 2 (LIKELY AFFECTED):
    authRouter [IMPORTS] -> src/routes/auth.ts

Manual editor setup

If you prefer manual configuration instead of gitnexus setup:

Claude Code

claude mcp add gitnexus -- npx -y gitnexus@latest mcp

Claude Code gets full integration: MCP + skills + PreToolUse hooks.

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

OpenCode

Add to ~/.config/opencode/config.json:

{
  "mcp": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp.json:

{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

Editor support

Editor	MCP	Skills	Hooks (auto-augment)	Support
Claude Code	✓	✓	✓ (PreToolUse)	Full
Cursor	✓	✓	—	MCP + Skills
Windsurf	✓	—	—	MCP
OpenCode	✓	✓	—	MCP + Skills

Claude Code gets the deepest integration with PreToolUse hooks that automatically enrich grep, glob, and bash calls with knowledge graph context.

Multi-repo workflow

GitNexus supports indexing multiple repositories:

1. Index each repository

   cd ~/projects/api && npx gitnexus analyze
   cd ~/projects/web && npx gitnexus analyze
   cd ~/projects/lib && npx gitnexus analyze
   
2. List indexed repos

   npx gitnexus list
   

   Shows all registered repositories with stats.

3. Use in agent

   With multiple repos indexed, the MCP server serves them all automatically.

   When only one repo is indexed, the repo parameter is optional:

   query({ query: "auth" })
   

   With multiple repos, specify which one:

   query({ query: "auth", repo: "api" })
   

Next steps

Core Concepts

Learn how the knowledge graph works

MCP Integration

Deep dive into MCP tools and resources

CLI Reference

Explore all CLI commands

Agent Skills

Master the 4 agent skills