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

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, the CLI writes a persistent hook entry that Claude Code loads on startup:

// 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, which serves as the CLI wrapper for the augmentation engine:

// 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, which interfaces with KuzuDB to retrieve semantic relationships:

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

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 verify handler registration:

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

Integration tests in gitnexus/test/integration/hooks-e2e.test.ts validate the full execution flow, including silent abort behavior when the working directory lacks GitNexus configuration:

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}