# How Claude Hooks in GitNexus Inject Knowledge Graph Context into CLI Commands

> Learn how GitNexus Claude hooks inject real time knowledge graph context into CLI commands. Enhance your AI developer workflow with enriched metadata from KuzuDB.

- Repository: [Abhigyan Patwari/GitNexus](https://github.com/abhigyanpatwari/GitNexus)
- Tags: how-to-guide
- Published: 2026-03-08

---

**GitNexus extends Claude Code with PreToolUse and PostToolUse hooks that automatically invoke the augmentation engine to enrich CLI outputs with knowledge graph metadata from KuzuDB before the AI model processes the results.**

The **Claude hooks in GitNexus** bridge the gap between static CLI tools and intelligent code understanding by intercepting shell commands in real-time. This integration allows Claude Code to reason about code relationships—callers, callees, and execution flows—without requiring manual context gathering or additional prompting.

## Understanding the Hook Architecture

GitNexus implements a bidirectional hook system that bookends CLI execution. The **PreToolUse** hook fires before Claude Code executes any shell tool, while the **PostToolUse** hook handles cleanup and reindexing after code changes.

These hooks reside in the Claude Code configuration layer and communicate with the GitNexus CLI through spawned subprocesses. When active, every `Grep`, `Glob`, or `Bash` command triggers an augmentation pipeline that queries the underlying knowledge graph.

## How the PreToolUse Hook Captures CLI Commands

### Hook Registration During Setup

The integration begins during the one-time initialization via `gitnexus setup`. In [`gitnexus/src/cli/setup.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/setup.ts), the CLI writes a persistent hook entry that Claude Code loads on startup:

```typescript
// gitnexus/src/cli/setup.ts
ensureHookEntry('PreToolUse', 'Grep|Glob|Bash', 10,
    'Enriching with GitNexus graph context...');

```

This registration targets specific tool types—**Grep**, **Glob**, and **Bash**—with a priority level of 10, ensuring the hook executes before the native tool handler.

### Command Interception and Validation

When Claude Code prepares to execute a matching tool, the PreToolUse handler validates the working directory and command context. If the directory contains a GitNexus configuration, the hook spawns the augmentation routine; otherwise, it silently passes through to prevent errors in non-GitNexus projects.

## The Augmentation Pipeline

### Spawning the Augment Command

The hook delegates heavy lifting to [`gitnexus/src/cli/augment.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/augment.ts), which serves as the CLI wrapper for the augmentation engine:

```typescript
// gitnexus/src/cli/augment.ts
// Shells out from Claude Code PreToolUse / Cursor beforeShellExecution hooks.

```

This module parses the original command pattern—such as the search term in a grep operation—and prepares it for graph querying.

### Querying the Knowledge Graph

The core logic resides in [`gitnexus/src/core/augmentation/engine.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/augmentation/engine.ts), which interfaces with **KuzuDB** to retrieve semantic relationships:

```typescript
// gitnexus/src/core/augmentation/engine.ts
// Designed to be called from platform hooks (Claude Code PreToolUse, Cursor beforeShellExecution)

```

The engine executes parameterized Cypher queries to fetch:
- **Callers**: Functions or methods invoking the target symbol
- **Callees**: Functions or methods called by the target symbol
- **Execution Flow IDs**: Unique identifiers for tracing runtime paths

### Injecting Context into Results

After retrieving graph data, the engine formats the output by appending `[GitNexus]` annotations to the original CLI results. The enriched string includes structured metadata about code relationships, which Claude Code receives as the final tool result.

For example, a standard grep for `loginUser` becomes:

```bash
loginUser   src/auth.ts   [GitNexus] callers: validateUser → loginUser, callees: setSession

```

This injection happens transparently—the AI model receives the augmented output without requiring explicit instructions to query the knowledge graph.

## PostToolUse Hook for Graph Maintenance

After Claude Code executes write operations such as commits or merges, the **PostToolUse** hook triggers automatic reindexing. This ensures the knowledge graph remains synchronized with the latest codebase state, preventing stale relationship data from polluting future queries.

The hook registration follows the same pattern as PreToolUse, targeting specific tool types that modify repository state.

## Testing and Validation

The hook system includes comprehensive test coverage across unit and integration layers.

Unit tests in [`gitnexus/test/unit/hooks.test.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/test/unit/hooks.test.ts) verify handler registration:

```typescript
expect(source).toContain('PreToolUse: handlePreToolUse');

```

Integration tests in [`gitnexus/test/integration/hooks-e2e.test.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/test/integration/hooks-e2e.test.ts) validate the full execution flow, including silent abort behavior when the working directory lacks GitNexus configuration:

```typescript
// Integration test for PreToolUse
describe('PreToolUse — silent without gitnexus CLI', () => { … });

```

## Summary

- **GitNexus** extends Claude Code through **PreToolUse** and **PostToolUse** hooks registered during `gitnexus setup`.
- The **PreToolUse** hook intercepts **Grep**, **Glob**, and **Bash** commands, spawning `gitnexus augment` to query the knowledge graph.
- The **augmentation engine** retrieves caller, callee, and execution-flow data from **KuzuDB** and injects `[GitNexus]` annotations into CLI outputs.
- Claude Code receives enriched results transparently, enabling architectural reasoning without manual context gathering.
- **PostToolUse** hooks maintain graph freshness by triggering reindexing after repository modifications.

## Frequently Asked Questions

### What are Claude hooks in GitNexus?

**Claude hooks in GitNexus** are integration points that extend Claude Code's native tool execution lifecycle. Specifically, GitNexus implements **PreToolUse** hooks that fire before shell commands execute and **PostToolUse** hooks that fire after write operations complete. These hooks are registered in Claude Code's configuration during the `gitnexus setup` command and enable automatic knowledge graph augmentation of CLI outputs.

### How does the PreToolUse hook know which commands to intercept?

The hook uses pattern matching defined during registration in [`gitnexus/src/cli/setup.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/setup.ts). The `ensureHookEntry` function specifies a regex pattern—`'Grep|Glob|Bash'`—that matches tool names in Claude Code's execution pipeline. When a user runs any command matching these patterns, such as a file search or shell execution, the hook handler triggers automatically with priority level 10, ensuring it executes before the native tool handler.

### What database does GitNexus use for the knowledge graph?

GitNexus uses **KuzuDB** as its underlying graph database engine. The augmentation engine in [`gitnexus/src/core/augmentation/engine.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/augmentation/engine.ts) executes Cypher queries against KuzuDB to retrieve semantic relationships including function callers, callees, and execution flow identifiers. This embedded graph database enables fast, local queries without requiring external database servers, making it suitable for CLI augmentation with minimal latency.

### How does the augmentation engine format the enriched output?

The engine appends structured metadata to the original CLI results using `[GitNexus]` annotations. For each symbol found in the command output, the engine queries the graph for caller and callee relationships, then formats these as comma-separated values appended to the line. For example, a grep result for `loginUser` becomes `loginUser src/auth.ts [GitNexus] callers: validateUser → loginUser, callees: setSession`. Claude Code receives this single enriched string as the tool result, allowing the model to reason about architectural relationships without additional tool calls.