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

# 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

<Steps>
  <Step title="Index your repository">
    Run from your repository root:

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

  <Step title="Configure your editor">
    Run the one-time setup:

    ```bash theme={null}
    npx gitnexus setup
    ```

    This auto-detects your editors and writes the correct MCP configuration.
  </Step>

  <Step title="Restart your editor">
    Restart your AI coding assistant to load the MCP server and skills.
  </Step>
</Steps>

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:

```typescript theme={null}
// Agent calls:
query({
  query: "authentication middleware",
  context: "user login flow",
  limit: 3
})
```

Response shows process-grouped results:

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

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

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add gitnexus -- npx -y gitnexus@latest mcp
    ```

    Claude Code gets full integration: MCP + skills + PreToolUse hooks.
  </Tab>

  <Tab title="Cursor">
    Add to `~/.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "gitnexus": {
          "command": "npx",
          "args": ["-y", "gitnexus@latest", "mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="OpenCode">
    Add to `~/.config/opencode/config.json`:

    ```json theme={null}
    {
      "mcp": {
        "gitnexus": {
          "command": "npx",
          "args": ["-y", "gitnexus@latest", "mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windsurf">
    Add to `~/.codeium/windsurf/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "gitnexus": {
          "command": "npx",
          "args": ["-y", "gitnexus@latest", "mcp"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Editor support

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

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

## Multi-repo workflow

GitNexus supports indexing multiple repositories:

<Steps>
  <Step title="Index each repository">
    ```bash theme={null}
    cd ~/projects/api && npx gitnexus analyze
    cd ~/projects/web && npx gitnexus analyze
    cd ~/projects/lib && npx gitnexus analyze
    ```
  </Step>

  <Step title="List indexed repos">
    ```bash theme={null}
    npx gitnexus list
    ```

    Shows all registered repositories with stats.
  </Step>

  <Step title="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:

    ```typescript theme={null}
    query({ query: "auth" })
    ```

    With multiple repos, specify which one:

    ```typescript theme={null}
    query({ query: "auth", repo: "api" })
    ```
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Core Concepts" icon="lightbulb" href="/concepts/knowledge-graph">
    Learn how the knowledge graph works
  </Card>

  <Card title="MCP Integration" icon="plug" href="/mcp/overview">
    Deep dive into MCP tools and resources
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli/overview">
    Explore all CLI commands
  </Card>

  <Card title="Agent Skills" icon="brain" href="/skills/overview">
    Master the 4 agent skills
  </Card>
</CardGroup>