How the Augment Hook in GitNexus Works with Claude Code PreToolUse

The augment hook in GitNexus intercepts Claude Code PreToolUse events—such as grep, glob, or bash commands containing ripgrep—to inject knowledge-graph context from the repository index, enriching the AI's understanding before the tool executes.

The augment hook bridges Claude Code's tool invocation system with GitNexus's semantic code knowledge graph. When developers use search tools within Claude Code, the hook automatically enhances queries with relevant context extracted from the repository's indexed structure.

Hook Invocation and Event Parsing

Claude Code triggers the augment hook by spawning gitnexus/hooks/claude/gitnexus-hook.cjs and feeding the hook event JSON via stdin. The readInput function parses this payload to extract critical metadata required for augmentation.

The hook expects the hook_event_name field to equal "PreToolUse" and captures three essential components:

• tool_name: Identifies the tool type (Grep, Glob, or Bash)
• tool_input: Contains the raw search parameters or command string
• cwd: The current working directory for repository resolution

Pattern Extraction and Normalization

The extractPattern function transforms diverse tool inputs into a standardized search term that the augmentation engine can process. Each tool type requires specific parsing logic:

Grep tools extract the pattern field directly from tool_input.

Glob tools parse the path pattern and isolate the first meaningful path segment, ignoring wildcards and file extensions to focus on directory structure.

Bash commands parse rg or grep invocations using argument tokenization. The function skips command flags (arguments starting with -) and returns the first non-flag argument containing three or more characters, ensuring meaningful search terms rather than single-letter options.

Repository Detection and CLI Resolution

Before executing augmentation, the hook must locate the GitNexus index and resolve the CLI binary.

Finding the .gitnexus Directory

The findGitNexusDir function walks up the directory tree from the current working directory, searching for a .gitnexus folder that contains the knowledge graph database. If no repository index is found, the hook aborts silently to prevent disrupting the user's workflow.

Resolving the CLI Path

The resolveCliPath function employs a three-tier resolution strategy to locate the gitnexus executable:

1. Bundled path: Checks dist/cli/index.js relative to the hook location
2. Global resolution: Uses require.resolve('gitnexus/dist/cli/index.js') for globally installed packages
3. npx fallback: Returns an empty string to trigger npx gitnexus execution when no local binary exists

Executing the Augment Command

The runGitNexusCli function executes the augmentation synchronously with a strict seven-second timeout to maintain responsiveness. The hook constructs and runs the command:

gitnexus augment -- <pattern>

Critical implementation detail: The augmentation CLI writes results to stderr rather than stdout because stdout is captured by the KuzuDB native module. The hook specifically captures child.stderr to retrieve the enriched context.

If the CLI execution fails, times out, or returns empty results, the hook handles these cases gracefully without throwing errors that could interrupt Claude Code's operation.

Returning Context to Claude Code

When the augmentation produces results, the hook formats a JSON payload and prints it to stdout:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "additionalContext": "<augmented text from knowledge graph>"
  }
}

Claude Code receives this payload and injects the additionalContext into the conversation flow, effectively prepending relevant code relationships, function definitions, and architectural context to the user's original search query.

Installation and Setup

The hook integrates with Claude Code through the setup command implemented in gitnexus/src/cli/setup.ts. Running gitnexus setup executes the installClaudeCodeHooks function, which:

• Copies gitnexus-hook.cjs to the appropriate hooks directory
• Merges PreToolUse and PostToolUse entries into ~/.claude/settings.json
• Configures the hook to trigger on relevant tool invocations

Once installed, any grep, rg, glob, or bash command containing search patterns automatically receives knowledge graph augmentation without requiring manual intervention.

Summary

• The augment hook intercepts Claude Code PreToolUse events via gitnexus/hooks/claude/gitnexus-hook.cjs to enrich search queries with repository context.
• Pattern extraction handles Grep, Glob, and Bash tools differently, normalizing inputs to extract meaningful search terms while filtering flags and wildcards.
• Repository detection requires a .gitnexus directory containing the knowledge graph index; the hook aborts silently if none exists.
• The CLI resolution strategy tries bundled paths, global npm installs, and falls back to npx to ensure the gitnexus augment command is always available.
• Results are captured from stderr (due to KuzuDB stdout capture) and returned to Claude Code as additionalContext in a JSON payload, seamlessly enriching the AI's understanding of the codebase.

Frequently Asked Questions

How does the augment hook handle different search tools like grep and glob?

The hook uses the extractPattern function to normalize inputs based on tool type. For Grep tools, it extracts the pattern field directly. For Glob tools, it isolates the first meaningful path segment while ignoring wildcards. For Bash commands, it tokenizes the command line, skips flag arguments starting with -, and returns the first substantive search term that is three or more characters long.

What happens if the GitNexus repository index is not found?

If the findGitNexusDir function cannot locate a .gitnexus directory when walking up from the current working directory, the hook aborts silently. This design ensures that Claude Code continues operating normally without errors, even when working in repositories that have not been indexed by GitNexus.

Why does the augment command write results to stderr instead of stdout?

The augmentation CLI writes to stderr because stdout is captured by the KuzuDB native module during execution. To ensure reliable communication between the CLI and the hook, the implementation deliberately uses stderr as the channel for returning augmented context. The runGitNexusCli function specifically captures child.stderr to retrieve these results.

How is the augment hook installed into Claude Code?

Installation occurs through the gitnexus setup command, which executes the installClaudeCodeHooks function in gitnexus/src/cli/setup.ts. This process copies the gitnexus-hook.cjs script to the appropriate location and merges PreToolUse and PostToolUse configuration entries into the user's ~/.claude/settings.json file, enabling automatic hook invocation on relevant tool uses.

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