gitnexus 1.1.8 → 1.2.0

package/README.md

@@ -18,31 +18,37 @@ AI coding tools don't understand your codebase structure. They edit a function w
 ## Quick Start
 
 ```bash
-# Install
-npm install -g gitnexus
+# Index your repo (run from repo root)
+npx gitnexus analyze
+```
 
-# One-time: configure MCP for your editors
-gitnexus setup
+That's it. This indexes the codebase, installs agent skills, registers Claude Code hooks, and creates `AGENTS.md` / `CLAUDE.md` context files — all in one command.
 
-# Index your repository (run from repo root)
-gitnexus analyze
+To configure MCP for your editor, run `npx gitnexus setup` once — or set it up manually below.
 
-# Done! Open your editor — MCP connects automatically.
-```
+`gitnexus setup` auto-detects your editors and writes the correct global MCP config. You only need to run it once.
 
-Or without installing globally:
+### Editor Support
 
-```bash
-npx gitnexus setup       # one-time
-npx gitnexus analyze     # per repo
-```
+| Editor | MCP | Skills | Hooks (auto-augment) | Support |
+|--------|-----|--------|---------------------|---------|
+| **Claude Code** | Yes | Yes | Yes (PreToolUse) | **Full** |
+| **Cursor** | Yes | Yes | — | MCP + Skills |
+| **Windsurf** | Yes | — | — | MCP |
+| **OpenCode** | Yes | Yes | — | MCP + Skills |
 
-The `setup` command auto-detects Cursor, Claude Code, and OpenCode, then writes the correct global MCP config. You only run it once.
+> **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that automatically enrich grep/glob/bash calls with knowledge graph context.
 
 ## MCP Setup (manual)
 
 If you prefer to configure manually instead of using `gitnexus setup`:
 
+### Claude Code (full support — MCP + skills + hooks)
+
+```bash
+claude mcp add gitnexus -- npx -y gitnexus@latest mcp
+```
+
 ### Cursor / Windsurf
 
 Add to `~/.cursor/mcp.json` (global — works for all projects):
@@ -58,12 +64,6 @@ Add to `~/.cursor/mcp.json` (global — works for all projects):
 }
 ```
 
-### Claude Code
-
-```bash
-claude mcp add gitnexus -- npx -y gitnexus@latest mcp
-```
-
 ### OpenCode
 
 Add to `~/.config/opencode/config.json`:
@@ -100,68 +100,59 @@ Your AI agent gets these tools automatically:
 | Tool | What It Does | `repo` Param |
 |------|-------------|--------------|
 | `list_repos` | Discover all indexed repositories | — |
-| `search` | Hybrid search (BM25 + semantic) with cluster context | Optional |
-| `overview` | List all clusters and processes | Optional |
-| `explore` | Deep dive on a symbol, cluster, or process | Optional |
-| `impact` | Blast radius analysis | Optional |
+| `query` | Process-grouped hybrid search (BM25 + semantic + RRF) | Optional |
+| `context` | 360-degree symbol view — categorized refs, process participation | Optional |
+| `impact` | Blast radius analysis with depth grouping and confidence | Optional |
+| `detect_changes` | Git-diff impact — maps changed lines to affected processes | Optional |
+| `rename` | Multi-file coordinated rename with graph + text search | Optional |
 | `cypher` | Raw Cypher graph queries | Optional |
-| `analyze` | Index or re-index a repository | Optional |
 
-> With one indexed repo, the `repo` param is optional. With multiple, specify which: `search({query: "auth", repo: "my-app"})`.
+> With one indexed repo, the `repo` param is optional. With multiple, specify which: `query({query: "auth", repo: "my-app"})`.
 
 ## MCP Resources
 
 | Resource | Purpose |
 |----------|---------|
 | `gitnexus://repos` | List all indexed repositories (read first) |
-| `gitnexus://repo/{name}/context` | Codebase stats and overview |
-| `gitnexus://repo/{name}/clusters` | All functional clusters |
+| `gitnexus://repo/{name}/context` | Codebase stats, staleness check, and available tools |
+| `gitnexus://repo/{name}/clusters` | All 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 |
+| `gitnexus://repo/{name}/process/{name}` | Full process trace with steps |
 | `gitnexus://repo/{name}/schema` | Graph schema for Cypher queries |
 
+## MCP Prompts
+
+| Prompt | What It Does |
+|--------|-------------|
+| `detect_impact` | Pre-commit change analysis — scope, affected processes, risk level |
+| `generate_map` | Architecture documentation from the knowledge graph with mermaid diagrams |
+
 ## CLI Commands
 
 ```bash
-gitnexus setup                # Configure MCP for your editors (one-time)
-gitnexus analyze [path]       # Index a repository (or update stale index)
-gitnexus analyze --force      # Force full re-index
-gitnexus mcp                  # Start MCP server (stdio) — serves all indexed repos
-gitnexus serve                # Start HTTP server for web UI
-gitnexus list                 # List all indexed repositories
-gitnexus status               # Show index status for current repo
-gitnexus clean                # Delete index for current repo
-gitnexus clean --all          # Delete all indexes
+gitnexus setup                    # Configure MCP for your editors (one-time)
+gitnexus analyze [path]           # Index a repository (or update stale index)
+gitnexus analyze --force          # Force full re-index
+gitnexus analyze --skip-embeddings  # Skip embedding generation (faster)
+gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
+gitnexus serve                   # Start HTTP server for web UI
+gitnexus list                    # List all indexed repositories
+gitnexus status                  # Show index status for current repo
+gitnexus clean                   # Delete index for current repo
+gitnexus clean --all --force     # Delete all indexes
+gitnexus wiki [path]             # Generate LLM-powered docs from knowledge graph
+gitnexus wiki --model <model>    # Wiki with custom LLM model (default: gpt-4o-mini)
 ```
 
 ## Multi-Repo Support
 
-GitNexus supports indexing multiple repositories. Each `gitnexus analyze` registers the repo in a global registry (`~/.gitnexus/registry.json`). The MCP server serves all indexed repos automatically with lazy KuzuDB connections.
+GitNexus supports indexing multiple repositories. Each `gitnexus analyze` registers the repo in a global registry (`~/.gitnexus/registry.json`). The MCP server serves all indexed repos automatically with lazy KuzuDB connections (max 5 concurrent, evicted after 5 minutes idle).
 
 ## Supported Languages
 
 TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust
 
-## How Impact Analysis Works
-
-```
-gitnexus_impact({target: "UserService", direction: "upstream", repo: "my-app"})
-
-TARGET: Class UserService (src/services/user.ts)
-
-UPSTREAM (what depends on this):
-  Depth 1 (direct callers):
-    handleLogin [CALLS 90%] → src/api/auth.ts:45
-    handleRegister [CALLS 90%] → src/api/auth.ts:78
-  Depth 2:
-    authRouter [IMPORTS] → src/routes/auth.ts
-
-8 files affected, 3 clusters touched
-```
-
-Options: `maxDepth`, `minConfidence`, `relationTypes`, `includeTests`
-
 ## Agent Skills
 
 GitNexus ships with skill files that teach AI agents how to use the tools effectively:
@@ -171,7 +162,7 @@ GitNexus ships with skill files that teach AI agents how to use the tools effect
 - **Impact Analysis** — Analyze blast radius before changes
 - **Refactoring** — Plan safe refactors using dependency mapping
 
-These are installed automatically to `.claude/skills/` when you run `gitnexus analyze`.
+Installed automatically by both `gitnexus analyze` (per-repo) and `gitnexus setup` (global).
 
 ## Requirements
 

package/dist/cli/ai-context.js

@@ -24,13 +24,12 @@ const GITNEXUS_END_MARKER = '<!-- gitnexus:end -->';
  * - Tools/Resources sections are labeled "Reference" — agents treat them as lookup, not workflow
  */
 function generateGitNexusContent(projectName, stats) {
-    const clusterCount = stats.clusters || stats.communities || 0;
     return `${GITNEXUS_START_MARKER}
 # GitNexus MCP
 
-This project is indexed by GitNexus as **${projectName}** (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${clusterCount} clusters, ${stats.processes || 0} processes).
+This project is indexed by GitNexus as **${projectName}** (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows).
 
-GitNexus provides a knowledge graph over this codebase — clusters, call chains, blast radius, execution flows, and semantic search.
+GitNexus provides a knowledge graph over this codebase — call chains, blast radius, execution flows, and semantic search.
 
 ## Always Start Here
 
@@ -55,10 +54,11 @@ For any task involving code understanding, debugging, impact analysis, or refact
 
 | Tool | What it gives you |
 |------|-------------------|
-| \`search\` | Semantic + keyword code search with cluster context |
-| \`explore\` | Symbol deep dive — callers, callees, cluster membership, processes |
-| \`impact\` | Blast radius — what breaks at depth 1/2/3 with confidence scores |
-| \`overview\` | All clusters and processes at a glance |
+| \`query\` | Process-grouped code intelligence — execution flows related to a concept |
+| \`context\` | 360-degree symbol view — categorized refs, processes it participates in |
+| \`impact\` | Symbol blast radius — what breaks at depth 1/2/3 with confidence |
+| \`detect_changes\` | Git-diff impact — what do your current changes affect |
+| \`rename\` | Multi-file coordinated rename with confidence-tagged edits |
 | \`cypher\` | Raw graph queries (read \`gitnexus://repo/{name}/schema\` first) |
 | \`list_repos\` | Discover indexed repos |
 
@@ -69,8 +69,8 @@ Lightweight reads (~100-500 tokens) for navigation:
 | Resource | Content |
 |----------|---------|
 | \`gitnexus://repo/{name}/context\` | Stats, staleness check |
-| \`gitnexus://repo/{name}/clusters\` | All clusters with cohesion scores |
-| \`gitnexus://repo/{name}/cluster/{clusterName}\` | Cluster members |
+| \`gitnexus://repo/{name}/clusters\` | All functional areas with cohesion scores |
+| \`gitnexus://repo/{name}/cluster/{clusterName}\` | Area members |
 | \`gitnexus://repo/{name}/processes\` | All execution flows |
 | \`gitnexus://repo/{name}/process/{processName}\` | Step-by-step trace |
 | \`gitnexus://repo/{name}/schema\` | Graph schema for Cypher |

package/dist/cli/analyze.js

@@ -4,17 +4,35 @@
  * Indexes a repository and stores the knowledge graph in .gitnexus/
  */
 import path from 'path';
-import ora from 'ora';
+import cliProgress from 'cli-progress';
 import { runPipelineFromRepo } from '../core/ingestion/pipeline.js';
-import { initKuzu, loadGraphToKuzu, getKuzuStats, executeQuery, executeWithReusedStatement, closeKuzu, createFTSIndex } from '../core/kuzu/kuzu-adapter.js';
+import { initKuzu, loadGraphToKuzu, getKuzuStats, executeQuery, executeWithReusedStatement, closeKuzu, createFTSIndex, loadCachedEmbeddings } from '../core/kuzu/kuzu-adapter.js';
 import { runEmbeddingPipeline } from '../core/embeddings/embedding-pipeline.js';
+import { disposeEmbedder } from '../core/embeddings/embedder.js';
 import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, getGlobalRegistryPath } from '../storage/repo-manager.js';
 import { getCurrentCommit, isGitRepo, getGitRoot } from '../storage/git.js';
 import { generateAIContextFiles } from './ai-context.js';
 import fs from 'fs/promises';
+import { registerClaudeHook } from './claude-hooks.js';
+/** Threshold: auto-skip embeddings for repos with more nodes than this */
+const EMBEDDING_NODE_LIMIT = 50_000;
+const PHASE_LABELS = {
+    extracting: 'Scanning files',
+    structure: 'Building structure',
+    parsing: 'Parsing code',
+    imports: 'Resolving imports',
+    calls: 'Tracing calls',
+    heritage: 'Extracting inheritance',
+    communities: 'Detecting communities',
+    processes: 'Detecting processes',
+    complete: 'Pipeline complete',
+    kuzu: 'Loading into KuzuDB',
+    fts: 'Creating search indexes',
+    embeddings: 'Generating embeddings',
+    done: 'Done',
+};
 export const analyzeCommand = async (inputPath, options) => {
-    const spinner = ora('Checking repository...').start();
-    // If path provided, use it directly. Otherwise, find git root from cwd.
+    console.log('\n  GitNexus Analyzer\n');
     let repoPath;
     if (inputPath) {
         repoPath = path.resolve(inputPath);
@@ -22,49 +40,85 @@ export const analyzeCommand = async (inputPath, options) => {
     else {
         const gitRoot = getGitRoot(process.cwd());
         if (!gitRoot) {
-            spinner.fail('Not inside a git repository');
+            console.log('  Not inside a git repository\n');
             process.exitCode = 1;
             return;
         }
         repoPath = gitRoot;
     }
     if (!isGitRepo(repoPath)) {
-        spinner.fail('Not a git repository');
+        console.log('  Not a git repository\n');
         process.exitCode = 1;
         return;
     }
     const { storagePath, kuzuPath } = getStoragePaths(repoPath);
     const currentCommit = getCurrentCommit(repoPath);
     const existingMeta = await loadMeta(storagePath);
-    // Skip if already indexed at same commit
     if (existingMeta && !options?.force && existingMeta.lastCommit === currentCommit) {
-        spinner.succeed('Repository already up to date');
+        console.log('  Already up to date\n');
         return;
     }
-    // Run ingestion pipeline
-    spinner.text = 'Running ingestion pipeline...';
+    // Single progress bar for entire pipeline
+    const bar = new cliProgress.SingleBar({
+        format: '  {bar} {percentage}% | {phase}',
+        barCompleteChar: '\u2588',
+        barIncompleteChar: '\u2591',
+        hideCursor: true,
+        barGlue: '',
+        autopadding: true,
+        clearOnComplete: false,
+        stopOnComplete: false,
+    }, cliProgress.Presets.shades_grey);
+    bar.start(100, 0, { phase: 'Initializing...' });
+    const t0Global = Date.now();
+    // ── Cache embeddings from existing index before rebuild ────────────
+    let cachedEmbeddingNodeIds = new Set();
+    let cachedEmbeddings = [];
+    if (existingMeta && !options?.force) {
+        try {
+            bar.update(0, { phase: 'Caching embeddings...' });
+            await initKuzu(kuzuPath);
+            const cached = await loadCachedEmbeddings();
+            cachedEmbeddingNodeIds = cached.embeddingNodeIds;
+            cachedEmbeddings = cached.embeddings;
+            await closeKuzu();
+        }
+        catch {
+            try {
+                await closeKuzu();
+            }
+            catch { }
+        }
+    }
+    // ── Phase 1: Full Pipeline (0–60%) ─────────────────────────────────
     const pipelineResult = await runPipelineFromRepo(repoPath, (progress) => {
-        spinner.text = `${progress.phase}: ${progress.percent}%`;
+        const phaseLabel = PHASE_LABELS[progress.phase] || progress.phase;
+        const scaled = Math.round(progress.percent * 0.6);
+        bar.update(scaled, { phase: phaseLabel });
     });
-    // Load graph into KuzuDB
-    // Always start fresh - remove existing kuzu DB to avoid stale/corrupt data
-    spinner.text = 'Loading graph into KuzuDB...';
+    // ── Phase 2: KuzuDB (60–85%) ──────────────────────────────────────
+    bar.update(60, { phase: 'Loading into KuzuDB...' });
     await closeKuzu();
-    // Kuzu 0.11 stores databases as: <name> (main file) + <name>.wal (WAL file)
-    // BOTH must be deleted or kuzu will find the orphaned WAL and corrupt the database
-    const fsClean = await import('fs/promises');
     const kuzuFiles = [kuzuPath, `${kuzuPath}.wal`, `${kuzuPath}.lock`];
     for (const f of kuzuFiles) {
         try {
-            await fsClean.rm(f, { recursive: true, force: true });
+            await fs.rm(f, { recursive: true, force: true });
         }
-        catch { /* may not exist */ }
+        catch { }
     }
+    const t0Kuzu = Date.now();
     await initKuzu(kuzuPath);
-    await loadGraphToKuzu(pipelineResult.graph, pipelineResult.fileContents, storagePath);
-    // Create FTS indexes for keyword search
-    // Indexes searchable content on: File, Function, Class, Method
-    spinner.text = 'Creating FTS indexes...';
+    let kuzuMsgCount = 0;
+    const kuzuResult = await loadGraphToKuzu(pipelineResult.graph, pipelineResult.fileContents, storagePath, (msg) => {
+        kuzuMsgCount++;
+        const progress = Math.min(84, 60 + Math.round((kuzuMsgCount / (kuzuMsgCount + 10)) * 24));
+        bar.update(progress, { phase: msg });
+    });
+    const kuzuTime = ((Date.now() - t0Kuzu) / 1000).toFixed(1);
+    const kuzuWarnings = kuzuResult.warnings;
+    // ── Phase 3: FTS (85–90%) ─────────────────────────────────────────
+    bar.update(85, { phase: 'Creating search indexes...' });
+    const t0Fts = Date.now();
     try {
         await createFTSIndex('File', 'file_fts', ['name', 'content']);
         await createFTSIndex('Function', 'function_fts', ['name', 'content']);
@@ -73,18 +127,47 @@ export const analyzeCommand = async (inputPath, options) => {
         await createFTSIndex('Interface', 'interface_fts', ['name', 'content']);
     }
     catch (e) {
-        // FTS index creation may fail if tables are empty (no data for that type)
-        console.error('Note: Some FTS indexes may not have been created:', e.message);
+        // Non-fatal — FTS is best-effort
     }
-    // Generate embeddings
-    if (!options?.skipEmbeddings) {
-        spinner.text = 'Generating embeddings...';
-        await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (progress) => {
-            spinner.text = `Embeddings: ${progress.percent}%`;
-        });
+    const ftsTime = ((Date.now() - t0Fts) / 1000).toFixed(1);
+    // ── Phase 3.5: Re-insert cached embeddings ────────────────────────
+    if (cachedEmbeddings.length > 0) {
+        bar.update(88, { phase: `Restoring ${cachedEmbeddings.length} cached embeddings...` });
+        const EMBED_BATCH = 200;
+        for (let i = 0; i < cachedEmbeddings.length; i += EMBED_BATCH) {
+            const batch = cachedEmbeddings.slice(i, i + EMBED_BATCH);
+            const paramsList = batch.map(e => ({ nodeId: e.nodeId, embedding: e.embedding }));
+            try {
+                await executeWithReusedStatement(`CREATE (e:CodeEmbedding {nodeId: $nodeId, embedding: $embedding})`, paramsList);
+            }
+            catch { /* some may fail if node was removed, that's fine */ }
+        }
     }
-    // Save metadata
+    // ── Phase 4: Embeddings (90–98%) ──────────────────────────────────
     const stats = await getKuzuStats();
+    let embeddingTime = '0.0';
+    let embeddingSkipped = false;
+    let embeddingSkipReason = '';
+    if (options?.skipEmbeddings) {
+        embeddingSkipped = true;
+        embeddingSkipReason = 'skipped (--skip-embeddings)';
+    }
+    else if (stats.nodes > EMBEDDING_NODE_LIMIT) {
+        embeddingSkipped = true;
+        embeddingSkipReason = `skipped (${stats.nodes.toLocaleString()} nodes > ${EMBEDDING_NODE_LIMIT.toLocaleString()} limit)`;
+    }
+    if (!embeddingSkipped) {
+        bar.update(90, { phase: 'Loading embedding model...' });
+        const t0Emb = Date.now();
+        await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (progress) => {
+            const scaled = 90 + Math.round((progress.percent / 100) * 8);
+            const label = progress.phase === 'loading-model' ? 'Loading embedding model...' : `Embedding ${progress.nodesProcessed || 0}/${progress.totalNodes || '?'}`;
+            bar.update(scaled, { phase: label });
+        }, {}, cachedEmbeddingNodeIds.size > 0 ? cachedEmbeddingNodeIds : undefined);
+        embeddingTime = ((Date.now() - t0Emb) / 1000).toFixed(1);
+    }
+    // ── Phase 5: Finalize (98–100%) ───────────────────────────────────
+    bar.update(98, { phase: 'Saving metadata...' });
     const meta = {
         repoPath,
         lastCommit: currentCommit,
@@ -98,14 +181,10 @@ export const analyzeCommand = async (inputPath, options) => {
         },
     };
     await saveMeta(storagePath, meta);
-    // Register in global registry
     await registerRepo(repoPath, meta);
-    // Add .gitnexus to .gitignore
     await addToGitignore(repoPath);
-    // Generate AI context files
+    const hookResult = await registerClaudeHook();
     const projectName = path.basename(repoPath);
-    // Compute aggregated cluster count (grouped by heuristicLabel, >=5 symbols)
-    // This matches the aggregation logic in local-backend.ts for tool output consistency.
     let aggregatedClusterCount = 0;
     if (pipelineResult.communityResult?.communities) {
         const groups = new Map();
@@ -123,22 +202,35 @@ export const analyzeCommand = async (inputPath, options) => {
         clusters: aggregatedClusterCount,
         processes: pipelineResult.processResult?.stats.totalProcesses,
     });
-    // Close database
     await closeKuzu();
-    spinner.succeed('Repository indexed successfully');
-    console.log(`  Path: ${repoPath}`);
-    console.log(`  Storage: ${storagePath}`);
-    console.log(`  Stats: ${stats.nodes} nodes, ${stats.edges} edges`);
+    await disposeEmbedder();
+    const totalTime = ((Date.now() - t0Global) / 1000).toFixed(1);
+    bar.update(100, { phase: 'Done' });
+    bar.stop();
+    // ── Summary ───────────────────────────────────────────────────────
+    const embeddingsCached = cachedEmbeddings.length > 0;
+    console.log(`\n  Repository indexed successfully (${totalTime}s)${embeddingsCached ? ` [${cachedEmbeddings.length} embeddings cached]` : ''}\n`);
+    console.log(`  ${stats.nodes.toLocaleString()} nodes | ${stats.edges.toLocaleString()} edges | ${pipelineResult.communityResult?.stats.totalCommunities || 0} clusters | ${pipelineResult.processResult?.stats.totalProcesses || 0} flows`);
+    console.log(`  KuzuDB ${kuzuTime}s | FTS ${ftsTime}s | Embeddings ${embeddingSkipped ? embeddingSkipReason : embeddingTime + 's'}`);
+    console.log(`  ${repoPath}`);
     if (aiContext.files.length > 0) {
-        console.log(`  AI Context: ${aiContext.files.join(', ')}`);
+        console.log(`  Context: ${aiContext.files.join(', ')}`);
+    }
+    if (hookResult.registered) {
+        console.log(`  Hooks: ${hookResult.message}`);
+    }
+    // Show warnings (missing schema pairs, etc.) after the clean output
+    if (kuzuWarnings.length > 0) {
+        console.log(`\n  Warnings (${kuzuWarnings.length}):`);
+        for (const w of kuzuWarnings) {
+            console.log(`    ${w}`);
+        }
     }
-    // Hint about setup if it hasn't been run
     try {
         await fs.access(getGlobalRegistryPath());
     }
     catch {
-        // Registry didn't exist before this run — suggest setup
-        console.log('');
-        console.log('  Tip: Run `gitnexus setup` to configure MCP for your editor.');
+        console.log('\n  Tip: Run `gitnexus setup` to configure MCP for your editor.');
     }
+    console.log('');
 };

package/dist/cli/augment.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Augment CLI Command
+ *
+ * Fast-path command for platform hooks.
+ * Shells out from Claude Code PreToolUse / Cursor beforeShellExecution hooks.
+ *
+ * Usage: gitnexus augment <pattern>
+ * Returns enriched text to stdout.
+ *
+ * Performance: Must cold-start fast (<500ms).
+ * Skips unnecessary initialization (no web server, no full DB warmup).
+ */
+export declare function augmentCommand(pattern: string): Promise<void>;

package/dist/cli/augment.js

@@ -0,0 +1,33 @@
+/**
+ * Augment CLI Command
+ *
+ * Fast-path command for platform hooks.
+ * Shells out from Claude Code PreToolUse / Cursor beforeShellExecution hooks.
+ *
+ * Usage: gitnexus augment <pattern>
+ * Returns enriched text to stdout.
+ *
+ * Performance: Must cold-start fast (<500ms).
+ * Skips unnecessary initialization (no web server, no full DB warmup).
+ */
+import { augment } from '../core/augmentation/engine.js';
+export async function augmentCommand(pattern) {
+    if (!pattern || pattern.length < 3) {
+        process.exit(0);
+    }
+    try {
+        const result = await augment(pattern, process.cwd());
+        if (result) {
+            // IMPORTANT: Write to stderr, NOT stdout.
+            // KuzuDB's native module captures stdout fd at OS level during init,
+            // which makes stdout permanently broken in subprocess contexts.
+            // stderr is never captured, so it works reliably everywhere.
+            // The hook reads from the subprocess's stderr.
+            process.stderr.write(result + '\n');
+        }
+    }
+    catch {
+        // Graceful failure — never break the calling hook
+        process.exit(0);
+    }
+}

package/dist/cli/claude-hooks.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Claude Code Hook Registration
+ *
+ * Registers the GitNexus PreToolUse hook in ~/.claude/hooks.json
+ * so that grep/glob/bash calls are automatically augmented with
+ * knowledge graph context.
+ *
+ * Idempotent — safe to call multiple times.
+ */
+/**
+ * Register (or verify) the GitNexus hook in Claude Code's global hooks.json.
+ *
+ * - Creates ~/.claude/ and hooks.json if they don't exist
+ * - Preserves existing hooks from other tools
+ * - Skips if GitNexus hook is already registered
+ *
+ * Returns a status message for the CLI output.
+ */
+export declare function registerClaudeHook(): Promise<{
+    registered: boolean;
+    message: string;
+}>;

package/dist/cli/claude-hooks.js

@@ -0,0 +1,97 @@
+/**
+ * Claude Code Hook Registration
+ *
+ * Registers the GitNexus PreToolUse hook in ~/.claude/hooks.json
+ * so that grep/glob/bash calls are automatically augmented with
+ * knowledge graph context.
+ *
+ * Idempotent — safe to call multiple times.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+/**
+ * Get the absolute path to the gitnexus-hook.js file.
+ * Works for both local dev and npm-installed packages.
+ */
+function getHookScriptPath() {
+    // From dist/cli/claude-hooks.js → hooks/claude/gitnexus-hook.js
+    const packageRoot = path.resolve(__dirname, '..', '..');
+    return path.join(packageRoot, 'hooks', 'claude', 'gitnexus-hook.cjs');
+}
+/**
+ * Register (or verify) the GitNexus hook in Claude Code's global hooks.json.
+ *
+ * - Creates ~/.claude/ and hooks.json if they don't exist
+ * - Preserves existing hooks from other tools
+ * - Skips if GitNexus hook is already registered
+ *
+ * Returns a status message for the CLI output.
+ */
+export async function registerClaudeHook() {
+    const claudeDir = path.join(os.homedir(), '.claude');
+    const hooksFile = path.join(claudeDir, 'hooks.json');
+    const hookScript = getHookScriptPath();
+    // Check if the hook script exists
+    try {
+        await fs.access(hookScript);
+    }
+    catch {
+        return { registered: false, message: 'Hook script not found (package may be incomplete)' };
+    }
+    // Build the hook command — use node + absolute path for reliability
+    const hookCommand = `node "${hookScript}"`;
+    // Check if ~/.claude/ exists (user has Claude Code installed)
+    try {
+        await fs.access(claudeDir);
+    }
+    catch {
+        // No Claude Code installation — skip silently
+        return { registered: false, message: 'Claude Code not detected (~/.claude/ not found)' };
+    }
+    // Read existing hooks.json or start fresh
+    let hooksConfig = {};
+    try {
+        const existing = await fs.readFile(hooksFile, 'utf-8');
+        hooksConfig = JSON.parse(existing);
+    }
+    catch {
+        // File doesn't exist or is invalid — we'll create it
+    }
+    // Ensure the hooks structure exists
+    if (!hooksConfig.hooks) {
+        hooksConfig.hooks = {};
+    }
+    if (!Array.isArray(hooksConfig.hooks.PreToolUse)) {
+        hooksConfig.hooks.PreToolUse = [];
+    }
+    // Check if GitNexus hook is already registered
+    const existingEntry = hooksConfig.hooks.PreToolUse.find((entry) => {
+        if (!entry.hooks || !Array.isArray(entry.hooks))
+            return false;
+        return entry.hooks.some((h) => h.command && (h.command.includes('gitnexus-hook') ||
+            h.command.includes('gitnexus augment')));
+    });
+    if (existingEntry) {
+        return { registered: true, message: 'Claude Code hook already registered' };
+    }
+    // Add the GitNexus hook entry
+    hooksConfig.hooks.PreToolUse.push({
+        matcher: {
+            tool_name: "Grep|Glob|Bash"
+        },
+        hooks: [
+            {
+                type: "command",
+                command: hookCommand,
+                timeout: 8000
+            }
+        ]
+    });
+    // Write back
+    await fs.writeFile(hooksFile, JSON.stringify(hooksConfig, null, 2) + '\n', 'utf-8');
+    return { registered: true, message: 'Claude Code hook registered' };
+}