gitnexus analyze

Index a repository into the knowledge graph

The analyze command processes a repository and builds a complete knowledge graph of its structure, dependencies, and execution flows.

Usage

gitnexus analyze [path] [options]

Arguments

path · string

Path to the repository to index. Defaults to current directory’s git root.

Options

force · boolean · default: "false"

Force full re-index even if already up to date. Use when the index is corrupted or after upgrading GitNexus.

Flag: -f, --force

embeddings · boolean · default: "false"

Enable embedding generation for semantic search. Automatically skipped for repositories with more than 50,000 symbols.

Flag: --embeddings

Examples

Basic Usage

Index the current repository:

cd my-project
npx gitnexus analyze

Index Specific Path

npx gitnexus analyze /path/to/repo

Force Re-index

gitnexus analyze --force

Enable Semantic Search

gitnexus analyze --embeddings

Output

The command displays a progress bar with real-time phase updates:

  GitNexus Analyzer

  ████████████████████░░░░ 85% | Creating search indexes...

Successful Indexing

  Repository indexed successfully (42.3s)

  1,348 nodes | 3,469 edges | 12 clusters | 104 flows
  KuzuDB 8.2s | FTS 1.1s | Embeddings off (use --embeddings to enable)
  /Users/dev/my-project
  Context: AGENTS.md, CLAUDE.md
  Hooks: Registered (PreToolUse)

Already Up to Date

  GitNexus Analyzer

  Already up to date

GitNexus tracks the current git commit hash. If you’re on the same commit as the last analysis, indexing is skipped unless you use --force.

Indexing Pipeline

The analyze command runs a multi-phase pipeline:

Phase 1: Code Analysis (0-60%)

1. Scanning files — Walks the file tree
2. Building structure — Maps folder hierarchy
3. Parsing code — Extracts functions, classes, methods using Tree-sitter
4. Resolving imports — Links imports to definitions
5. Tracing calls — Builds function call graph
6. Extracting inheritance — Maps class hierarchies
7. Detecting communities — Groups related symbols into functional clusters
8. Detecting processes — Traces execution flows from entry points

Phase 2: Graph Database (60-85%)

Loads the graph into KuzuDB for fast querying.

Phase 3: Search Indexes (85-90%)

Creates full-text search indexes for:

• Files
• Functions
• Classes
• Methods
• Interfaces

Phase 4: Embeddings (90-98%, optional)

Generates semantic embeddings for hybrid search. Only runs when --embeddings is enabled and symbol count is under 50,000.

Phase 5: Finalization (98-100%)

• Saves metadata to .gitnexus/meta.json
• Registers repository in global registry
• Adds .gitnexus/ to .gitignore
• Generates AGENTS.md and CLAUDE.md context files
• Installs agent skills (per-repo)
• Registers Claude Code hooks (if applicable)

Generated Files

.gitnexus/ Directory

.gitnexus/
├── db/              # KuzuDB graph database
└── meta.json        # Index metadata

Context Files

AGENTS.md — Instructions for AI agents on how to use the knowledge graph

CLAUDE.md — Claude Code-specific context (same as AGENTS.md, different filename for compatibility)

Skills Directory

.claude/skills/gitnexus/ — Agent skills for exploring, debugging, impact analysis, and refactoring (Claude Code only)

Performance

Typical Performance

Repository Size	Time	Memory
Small (< 100 files)	5-15s	500 MB
Medium (100-1,000 files)	15-60s	1-2 GB
Large (1,000-10,000 files)	1-5 min	2-4 GB
Very Large (10,000+ files)	5-20 min	4-8 GB

Memory Management

GitNexus automatically allocates 8GB heap for large repositories. It re-spawns with increased memory if needed.

For repositories with 10,000+ files, ensure you have at least 10GB free RAM to avoid swapping.

Embeddings

Semantic search is disabled by default for performance reasons.

When to Enable Embeddings

• You want semantic “find similar code” queries
• Repository has fewer than 50,000 symbols
• You have time for longer indexing

Automatic Skipping

Embeddings are automatically skipped when:

Embeddings skipped (78,432 nodes > 50,000 limit)

Caching

Embeddings are cached between re-indexes. Only new or changed symbols are re-embedded.

Troubleshooting

”Not inside a git repository”

GitNexus requires a git repository. Initialize one first:

git init

Process Crashes / Out of Memory

Increase heap size:

NODE_OPTIONS="--max-old-space-size=16384" gitnexus analyze

Embeddings Segfault

This is a known issue with ONNX Runtime on some platforms. The process force-exits after completion to bypass the crash. Your index is safe.

Stale Index Warning

If commits have been made since last indexing:

gitnexus analyze  # Re-run to update

See Also

• gitnexus status — Check if index is up to date
• gitnexus clean — Remove index
• gitnexus list — View all indexed repos