GitNexus Essentials

Complete guide to using GitNexus for intelligent code navigation, impact analysis, and refactoring.

What is GitNexus?

GitNexus is an AI-powered code intelligence tool that builds a knowledge graph of your codebase, enabling advanced code navigation, impact analysis, and safe refactoring.

Key Features:

Knowledge graph of code relationships

Impact analysis before making changes

Safe refactoring with dependency tracking

Code exploration and navigation

Debugging and error tracing

Architecture visualization

Installation

Prerequisites

Before installing GitNexus, ensure you have:

Node.js 18+ installed

Git repository initialized

Install GitNexus

# Option 1: Install globally
npm install -g gitnexus

# Option 2: Use with npx (no installation required)
npx gitnexus <command>

Verify Installation:

npx gitnexus --version

Core Concepts

Knowledge Graph

GitNexus builds a graph database containing:

Nodes: Code entities (files, functions, classes, types)

Edges: Relationships (imports, calls, extends, implements)

Clusters: Logical groupings of related code

Flows: Execution and data flows

Index Structure

.gitnexus/
├── index.db        # Knowledge graph database
├── cache/          # Analysis cache
└── config.json     # Configuration

Basic Commands

Initialize and Analyze

# Step 1: Analyze current repository
npx gitnexus analyze

# Step 2: Analyze specific directory only
npx gitnexus analyze ./src

# Step 3: Force complete re-analysis (ignores cache)
npx gitnexus analyze --force

Expected Output:

✓ Repository indexed successfully (5.4s)
  • 1,343 nodes (code entities)
  • 1,666 edges (relationships)
  • 12 clusters (logical groups)
  • 38 flows (execution paths)

Check Status

# View index status
npx gitnexus status

# Output shows:
# - Last indexed commit
# - Number of nodes/edges
# - Index freshness

Clean Index

# Remove index and start fresh
npx gitnexus clean

# Remove cache only
npx gitnexus clean --cache-only

Code Exploration

Finding Code

# Search for symbol
npx gitnexus query "ContactForm"

# Find all usages
npx gitnexus usages ContactForm

# Find definition
npx gitnexus definition ContactForm

Navigate Relationships

# What does this import?
npx gitnexus imports components/contact/ContactForm.tsx

# What imports this?
npx gitnexus imported-by components/contact/ContactForm.tsx

# Show all dependencies
npx gitnexus dependencies components/contact/

Impact Analysis

⚠️ Always run impact analysis before modifying any file

Before Making Changes

# Check what depends on this file
npx gitnexus impact components/ui/Button.tsx

Understanding the Output

The impact report shows:

Direct dependents: Files that directly import/use this file

Indirect dependents: Files affected through the dependency chain

Affected test files: Tests that may need updating

Risk assessment: LOW, MEDIUM, HIGH, or CRITICAL

Example Output

Impact Analysis: components/ui/Button.tsx
════════════════════════════════════════════════════════════

📊 Direct Dependents (12 files):
  • app/[lang]/contact/page.tsx
  • components/contact/ContactForm.tsx
  • components/content/Hero.tsx
  • (9 more files...)

🔗 Indirect Dependents (45 files):
  • app/[lang]/about/page.tsx
  • app/[lang]/resume/page.tsx
  • (43 more files...)

⚠️  Risk Level: MEDIUM
💡 Recommendation: Run tests in affected modules before merging

Refactoring

Rename Symbol

# Rename function across codebase
npx gitnexus rename oldFunction newFunction

# Rename component
npx gitnexus rename ContactForm ContactFormV2

Move File

# Move file and update all imports
npx gitnexus move src/old/path.ts src/new/path.ts

# Move directory
npx gitnexus move components/old/ components/new/

Extract Component

# Extract code into new component
npx gitnexus extract components/Form.tsx "FormField" --to components/FormField.tsx

Debugging

Trace Errors

# Trace where error originates
npx gitnexus trace "Cannot read property 'name'"

# Find error handlers
npx gitnexus query "try.*catch"

Find Call Chains

# How does data flow from A to B?
npx gitnexus flow-from validateForm --to submitForm

# Show all paths
npx gitnexus paths ContactForm.handleSubmit --to fetch

Architecture Visualization

Generate Diagrams

# Visualize module structure
npx gitnexus visualize --output architecture.svg

# Component dependency graph
npx gitnexus graph components/ --output components.png

Export Documentation

# Generate architecture wiki
npx gitnexus wiki --output docs/architecture/

# Export to Markdown
npx gitnexus export --format markdown --output ARCHITECTURE.md

Integration with Claude Code

GitNexus integrates seamlessly with Claude Code through MCP (Model Context Protocol).

Available MCP Tools

When using Claude Code, you can ask Claude to:

"What will break if I change this function?"
→ Uses gitnexus__impact

"Show me how this component is used"
→ Uses gitnexus__query

"Help me refactor this safely"
→ Uses gitnexus__shape_check

Claude Skills

GitNexus provides several skills in Claude Code:

gitnexus-exploring: Understand how code works gitnexus-debugging: Trace bugs and errors gitnexus-refactoring: Safe code refactoring gitnexus-impact-analysis: Assess change impact gitnexus-cli: Repository analysis commands

Configuration

.gitnexus/config.json

{
  "include": [
    "src/**/*.ts",
    "src/**/*.tsx",
    "components/**/*.tsx"
  ],
  "exclude": [
    "**/*.test.ts",
    "**/*.spec.ts",
    "**/node_modules/**"
  ],
  "analysis": {
    "depth": "deep",
    "includeTests": false,
    "trackTypes": true
  }
}

Common Configurations

Ignore Test Files:

{
  "exclude": ["**/*.test.*", "**/*.spec.*"]
}

Focus on Specific Directories:

{
  "include": ["src/**", "components/**"]
}

Best Practices

Keep Index Fresh

# Run after pulling changes
git pull && npx gitnexus analyze

# Set up git hook
echo "npx gitnexus analyze" > .git/hooks/post-merge
chmod +x .git/hooks/post-merge

Before Major Refactoring

Analyze impact: Check what depends on the code

Review flows: Understand execution paths

Check tests: Ensure test coverage

Refactor: Use GitNexus rename/move tools

Re-analyze: Update the index

Performance Tips

Exclude large generated files

Use --incremental for faster analysis

Clear cache if index is stale

Analyze during idle time for large repos

Common Workflows

Adding New Component

# 1. Check for similar components
npx gitnexus query "ContactForm"

# 2. Find patterns to follow
npx gitnexus imports components/contact/ContactForm.tsx

# 3. Create component
# (create your file)

# 4. Update index
npx gitnexus analyze

Debugging Production Issue

# 1. Find error in code
npx gitnexus query "error message"

# 2. Trace call chain
npx gitnexus flow-from entry --to errorFunction

# 3. Find all error handlers
npx gitnexus query "catch.*Error"

# 4. Check recent changes
git log --oneline -- affected/file.ts

Safe Refactoring

# 1. Check impact
npx gitnexus impact components/ui/Button.tsx

# 2. Review dependents
npx gitnexus imported-by components/ui/Button.tsx

# 3. Rename/move using GitNexus
npx gitnexus rename Button PrimaryButton

# 4. Verify no broken imports
npm run build

Troubleshooting

Index Out of Date

Problem: GitNexus shows old results

Solution:

npx gitnexus clean
npx gitnexus analyze --force

Analysis Too Slow

Problem: Analysis takes too long

Solution:

# Exclude large directories
# Update .gitnexus/config.json
{
  "exclude": ["**/dist/**", "**/build/**", "**/.next/**"]
}

Missing Dependencies

Problem: Some relationships not found

Solution:

# Increase analysis depth
npx gitnexus analyze --depth deep

# Include test files
npx gitnexus analyze --include-tests

Advanced Usage

Custom Queries

# Find all async functions
npx gitnexus query "async function"

# Find React hooks
npx gitnexus query "use[A-Z].*"

# Find TODO comments
npx gitnexus query "TODO:"

Export for CI/CD

# Generate impact report
npx gitnexus impact --json > impact-report.json

# Check if change affects critical paths
npx gitnexus check-critical --files changed-files.txt

Integration with Other Tools

# Export to Neo4j
npx gitnexus export --format neo4j --output graph.cypher

# Generate TypeScript definitions
npx gitnexus types --output types/graph.d.ts

Resources

Official Docs: https://gitnexus.dev/docs

GitHub: https://github.com/gitnexus/gitnexus

Examples: https://gitnexus.dev/examples

Community: https://discord.gg/gitnexus

Quick Reference Card

# Analysis
npx gitnexus analyze                 # Index codebase
npx gitnexus status                  # Check status
npx gitnexus clean                   # Clear index

# Exploration
npx gitnexus query "symbol"          # Search code
npx gitnexus usages Symbol           # Find usages
npx gitnexus definition Symbol       # Find definition

# Impact Analysis
npx gitnexus impact file.ts          # Check impact
npx gitnexus dependencies path/      # Show deps

# Refactoring
npx gitnexus rename old new          # Rename symbol
npx gitnexus move old.ts new.ts      # Move file

# Debugging
npx gitnexus trace "error"           # Trace error
npx gitnexus flow-from A --to B      # Show flow

# Visualization
npx gitnexus visualize               # Generate diagram
npx gitnexus wiki                    # Create wiki

Next Steps

Run npx gitnexus analyze on your project

Try exploring code with npx gitnexus query

Check impact before making changes

Use GitNexus skills in Claude Code

---

Last Updated: 2026-04-20 GitNexus Version: 1.x Difficulty: Intermediate