> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/abhigyanpatwari/GitNexus/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
gitnexus analyze [path] [options]
```

## Arguments

<ParamField path="path" type="string" optional>
  Path to the repository to index. Defaults to current directory's git root.
</ParamField>

## Options

<ParamField query="force" type="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`
</ParamField>

<ParamField query="embeddings" type="boolean" default="false">
  Enable embedding generation for semantic search. Automatically skipped for repositories with more than 50,000 symbols.

  **Flag:** `--embeddings`
</ParamField>

## Examples

### Basic Usage

Index the current repository:

```bash theme={null}
cd my-project
npx gitnexus analyze
```

### Index Specific Path

```bash theme={null}
npx gitnexus analyze /path/to/repo
```

### Force Re-index

```bash theme={null}
gitnexus analyze --force
```

### Enable Semantic Search

```bash theme={null}
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
```

<Note>
  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`.
</Note>

## 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.

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

## 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:

```bash theme={null}
git init
```

### Process Crashes / Out of Memory

Increase heap size:

```bash theme={null}
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:

```bash theme={null}
gitnexus analyze  # Re-run to update
```

## See Also

* [gitnexus status](/cli/status) — Check if index is up to date
* [gitnexus clean](/cli/clean) — Remove index
* [gitnexus list](/cli/list) — View all indexed repos