pi-gitnexus 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## 0.3.0
+
+- **TypeScript compatibility** — `tool_result` handler now uses inferred event types from the API overload instead of a manual annotation, fixing a compile error with `@mariozechner/pi-coding-agent` 0.54.x.
+- **Dependency updates** — `@mariozechner/pi-coding-agent` to 0.54.2, `@types/node` to 25.x.
+
+## 0.2.0
+
+### Features
+
+- **`read` tool augmentation** — file reads now trigger augmentation. When the agent reads a code file (`.sol`, `.ts`, `.go`, etc.), the filename is used as the lookup pattern to get callers/callees for that file's symbols.
+- **Bash `cat`/`head`/`tail` support** — extractPattern now handles `cat file.sol`, `head file.sol`, etc. alongside grep/rg/find.
+- **Multi-pattern augmentation** — each tool result now augments up to 3 patterns in parallel: the primary pattern from the tool input, plus filenames extracted from grep output lines (`path/file.sol:line:`). Results are merged into a single `[GitNexus]` block.
+- **Session dedup cache** — each symbol/filename is augmented at most once per session, preventing redundant lookups when the agent repeatedly searches for the same thing.
+
+### Fixes
+
+- **Auto-augment now works** — `gitnexus augment` writes its output to stderr, not stdout. `runAugment` was capturing stdout only, so every augmentation returned empty. Fixed by reading from stderr (`stdio: ['ignore', 'ignore', 'pipe']`).
+- **Regex patterns cleaned before augment** — grep/rg patterns like `\bwithdraw\s*\(` are stripped of regex metacharacters before passing to `gitnexus augment`, which expects a plain symbol name.
+- **`gitnexus_query` limit raised** — max `limit` parameter increased from 20 to 100. The agent was hitting validation errors when requesting more results.
+- **Status counters** — `/gitnexus status` now shows searches intercepted and enrichment count for observability.
+
+## 0.1.0
+
+Initial release.
+
+### Features
+
+- **Auto-augment hook** — intercepts grep, find, and bash tool results and appends knowledge graph context (callers, callees, execution flows) via `gitnexus augment`. Mirrors the Claude Code plugin's PreToolUse integration.
+- **Five registered tools** — `gitnexus_list_repos`, `gitnexus_query`, `gitnexus_context`, `gitnexus_impact`, `gitnexus_detect_changes` available to the agent with zero setup.
+- **stdio MCP client** — tools communicate with `gitnexus mcp` over a stdin/stdout pipe (no network socket, no port). Process is spawned lazily and kept alive for the session.
+- **System prompt hint** — when an index is present, appends a one-liner to the agent's system prompt so it understands graph context and knows to use the tools.
+- **Session lifecycle** — on session start/switch: resolves full shell PATH (nvm/fnm/volta), probes binary, checks index, notifies status. MCP process restarted on session switch.
+- **`/gitnexus` command** with subcommands: `status`, `analyze`, `on`, `off`, `query`, `context`, `impact`, `<pattern>`, `help`.
+- **`/gitnexus analyze`** — runs `gitnexus analyze` from within pi with start/completion notifications. Auto-augment is paused for the duration to avoid stale index results.
+- **Toggle** — `/gitnexus on` / `/gitnexus off` enables/disables auto-augment without affecting tools. Resets to enabled on session switch.
+- **Shell PATH resolution** — spawns `$SHELL -lc 'echo $PATH'` on session start so nvm/fnm/volta-managed binaries are found when pi is launched as a GUI app.
+- **Path traversal guard** — `gitnexus_context` file parameter validated to stay within cwd before passing to the MCP server.
+- **Graceful failure** — every code path (augment timeout, MCP spawn error, binary missing) returns empty rather than throwing. Extension never breaks the agent's normal flow.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tintinweb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# pi-gitnexus
+
+[GitNexus](https://github.com/abhigyanpatwari/GitNexus) knowledge graph integration for [pi](https://github.com/mariozechner/pi). Enriches every search, file read, and symbol lookup with call chains, callers/callees, and execution flows — automatically.
+
+<img height="298" alt="pi-gitnexus screenshot" src="https://github.com/tintinweb/pi-gitnexus/raw/master/media/screenshot.png" />
+
+
+https://github.com/user-attachments/assets/49e61667-f508-4d22-abad-05241e414664
+
+> The graph view in the demo is from [gitnexus-web](https://github.com/abhigyanpatwari/GitNexus) and is not part of this extension.
+
+## What it does
+
+When the agent reads a file or runs a search (grep, find, bash), the extension appends graph context from the knowledge graph inline with the results. The agent sees both together and can follow call chains without additional queries.
+
+```
+Agent reads auth/session.ts
+  → file content returned normally
+  → [GitNexus] appended: callers of the module, what it imports, related tests
+
+Agent runs grep("validateUser")
+  → grep results returned normally
+  → [GitNexus] appended: Called by: login, signup / Calls: checkPermissions, getUser
+  → filenames in the grep output are also looked up in parallel
+```
+
+Five tools are also registered directly in pi — the agent can use them explicitly for deeper analysis without any setup.
+
+## Requirements
+
+- [gitnexus](https://github.com/abhigyanpatwari/GitNexus) installed globally: `npm i -g gitnexus`
+- A GitNexus index in your project: run `/gitnexus analyze`
+
+## Getting started
+
+1. Install gitnexus: `npm i -g gitnexus`
+2. Open your project in pi
+3. Run `/gitnexus analyze` to build the knowledge graph
+4. Done — file reads and searches are now enriched automatically
+
+## What triggers augmentation
+
+| Tool | Pattern used |
+|---|---|
+| `grep` | Search pattern (regex metacharacters stripped) |
+| `bash` with grep/rg | First non-flag argument after `grep`/`rg` |
+| `bash` with cat/head/tail | Filename of the target file |
+| `bash` with find | Value of `-name`/`-iname` |
+| `find` | Glob pattern basename |
+| `read` | Filename of the file being read (code files only) |
+| Any grep/bash result | Filenames extracted from result lines (`path/file.sol:line:`) |
+
+Each tool result augments up to 3 patterns in parallel. Patterns already augmented this session are skipped.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `/gitnexus` | Show index status and session enrichment count |
+| `/gitnexus analyze` | Build or rebuild the knowledge graph |
+| `/gitnexus on` / `/gitnexus off` | Enable/disable auto-augment (tools unaffected) |
+| `/gitnexus <pattern>` | Manual graph lookup for a symbol or pattern |
+| `/gitnexus query <text>` | Search execution flows |
+| `/gitnexus context <name>` | 360° view of a symbol: callers, callees, processes |
+| `/gitnexus impact <name>` | Upstream blast radius of a change |
+| `/gitnexus help` | Show command reference |
+
+## Agent tools
+
+The following tools are registered in pi and always available to the agent:
+
+| Tool | Description |
+|---|---|
+| `gitnexus_list_repos` | List all indexed repositories |
+| `gitnexus_query` | Search the knowledge graph for execution flows |
+| `gitnexus_context` | 360° view of a symbol: callers, callees, processes |
+| `gitnexus_impact` | Blast radius analysis for a symbol |
+| `gitnexus_detect_changes` | Map a git diff to affected execution flows |
+
+## How it works
+
+**Auto-augment hook** — fires after every grep/find/bash/read tool result. Extracts up to 3 patterns (primary from input, secondary filenames from result content) and calls `gitnexus augment` for each in parallel. Results are merged into a single `[GitNexus]` block appended to the tool result, so the agent sees it inline.
+
+**Session dedup cache** — each symbol or filename is augmented at most once per session. Prevents redundant lookups when the agent repeatedly searches for the same thing.
+
+**MCP client** — tools (query, context, impact, detect_changes, list_repos) communicate with `gitnexus mcp` over a stdio pipe. The process is spawned lazily on the first tool call and kept alive for the session. No network socket, no port.
+
+**Session lifecycle** — on session start/switch, the extension resolves the full shell PATH (picking up nvm/fnm/volta), probes the binary, checks for an index, and notifies accordingly. The MCP process is restarted with the new working directory.
+
+**Auto-augment toggle** — `/gitnexus off` disables the hook without affecting tools. Useful when the graph output is noisy for a particular task. Resets to enabled on session switch.
+
+**Analyze guard** — auto-augment is paused during `/gitnexus analyze` to avoid injecting stale or partially-built index results.
+
+## License note
+
+This extension (pi-gitnexus) is MIT licensed. [GitNexus](https://github.com/abhigyanpatwari/GitNexus) itself is published under the [PolyForm Noncommercial License](https://polyformproject.org/licenses/noncommercial/1.0.0/) — commercial use requires a separate agreement with its author. Install and use gitnexus in accordance with its license terms.
+
+## Notes
+
+- The index is a static snapshot. Re-run `/gitnexus analyze` after significant code changes. The agent will suggest this when the index appears stale.
+- `gitnexus_detect_changes` is a lightweight alternative: pass `git diff HEAD` output to see affected flows without a full reindex.
+- `gitnexus_cypher` and `gitnexus_rename` are intentionally not exposed (raw graph access and automated multi-file rename).
+- The enrichment is appended to the tool result the agent receives — files on disk and raw tool outputs are never modified.

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "pi-gitnexus",
+  "version": "0.2.1",
+  "description": "GitNexus knowledge graph integration for pi — enriches searches with call chains, execution flows, and blast radius",
+  "author": "tintinweb",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "gitnexus",
+    "knowledge-graph",
+    "code-intelligence",
+    "call-graph",
+    "agent"
+  ],
+  "dependencies": {
+    "@mariozechner/pi-coding-agent": "latest",
+    "@sinclair/typebox": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.0.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "image": "https://github.com/tintinweb/pi-gitnexus/raw/master/media/screenshot.png"
+  }
+}

package/src/gitnexus.ts

@@ -0,0 +1,204 @@
+import { spawn } from 'child_process';
+import { resolve, sep, basename, extname } from 'path';
+import { existsSync } from 'fs';
+
+/** Max output chars returned to the LLM. Prevents context flooding. JS strings are UTF-16 chars, not bytes. */
+export const MAX_OUTPUT_CHARS = 8 * 1024;
+
+/**
+ * Environment passed to all child processes.
+ * Resolved from a login shell on session_start to pick up nvm/fnm/volta PATH entries
+ * that are missing when pi launches as a GUI app.
+ */
+export let spawnEnv: NodeJS.ProcessEnv = process.env;
+export function updateSpawnEnv(env: NodeJS.ProcessEnv): void { spawnEnv = env; }
+
+/** Augment subprocess timeout in ms. Applied via setTimeout + proc.kill('SIGTERM') — spawn has no built-in timeout. */
+const AUGMENT_TIMEOUT = 8_000;
+
+/** Per-cwd cache: true = index found, false = not found. Invalidated on session_switch. */
+const indexCache = new Map<string, boolean>();
+
+/** Walk up to 5 ancestors looking for a .gitnexus/ directory. Result is cached per cwd. */
+export function findGitNexusIndex(cwd: string): boolean {
+  if (indexCache.has(cwd)) return indexCache.get(cwd)!;
+  let dir = cwd;
+  for (let i = 0; i < 5; i++) {
+    if (existsSync(resolve(dir, '.gitnexus'))) {
+      indexCache.set(cwd, true);
+      return true;
+    }
+    const parent = resolve(dir, '..');
+    if (parent === dir) break;
+    dir = parent;
+  }
+  indexCache.set(cwd, false);
+  return false;
+}
+
+/** Clear the index cache. Call on session_switch when cwd may have changed. */
+export function clearIndexCache(): void {
+  indexCache.clear();
+}
+
+/** File extensions worth augmenting when the agent reads a file. */
+const CODE_EXTENSIONS = new Set([
+  '.sol', '.ts', '.tsx', '.js', '.jsx', '.py', '.go', '.rs', '.java',
+  '.kt', '.swift', '.c', '.cpp', '.h', '.hpp', '.cs', '.rb', '.php',
+  '.vy', '.fe', '.huff',
+]);
+
+/**
+ * Extract the primary search pattern from a tool's input object.
+ *
+ * grep  → input.pattern
+ * find  → basename of the glob pattern (e.g. "**\/foo.ts" → "foo")
+ * bash  → grep/rg pattern, find -name value, or cat/head/tail filename
+ * read  → basename of the file path (code files only)
+ *
+ * Returns null if pattern is missing or shorter than 3 chars.
+ */
+export function extractPattern(toolName: string, input: Record<string, unknown>): string | null {
+  let pattern: string | null = null;
+
+  if (toolName === 'grep') {
+    const raw = typeof input.pattern === 'string' ? input.pattern : null;
+    // Strip regex metacharacters — gitnexus augment expects a plain symbol/identifier name.
+    pattern = raw ? raw.replace(/[\\^$.*+?()[\]{}|]/g, '') : null;
+  } else if (toolName === 'find') {
+    // pi's find tool field name is unconfirmed — try common variants
+    const raw =
+      typeof input.pattern === 'string' ? input.pattern :
+      typeof input.glob    === 'string' ? input.glob    :
+      typeof input.path    === 'string' ? input.path    :
+      null;
+    if (raw) {
+      const seg = basename(raw).replace(/\.\w+$/, '').replace(/[*?[\]{}]/g, '');
+      pattern = seg || null;
+    }
+  } else if (toolName === 'bash') {
+    const cmd = typeof input.command === 'string' ? input.command : '';
+    const tokens = cmd.split(/\s+/);
+    let foundCmd = false;
+    let foundFileCmd = false;
+    for (let i = 0; i < tokens.length; i++) {
+      const tok = tokens[i];
+
+      // grep/rg: first non-flag arg after the command is the search pattern
+      if (tok === 'grep' || tok === 'rg') { foundCmd = true; foundFileCmd = false; continue; }
+      if (foundCmd) {
+        if (tok.startsWith('-')) continue;
+        // Strip quotes and regex metacharacters — gitnexus augment expects a plain symbol name.
+        pattern = tok.replace(/['"]/g, '').replace(/[\\^$.*+?()[\]{}|]/g, '');
+        break;
+      }
+
+      // cat / head / tail / less / wc: next non-flag arg is a file path → use basename
+      if (tok === 'cat' || tok === 'head' || tok === 'tail' || tok === 'less' || tok === 'wc') {
+        foundFileCmd = true; foundCmd = false; continue;
+      }
+      if (foundFileCmd) {
+        if (tok.startsWith('-')) continue;
+        const unquoted = tok.replace(/['"]/g, '');
+        const ext = extname(unquoted);
+        if (CODE_EXTENSIONS.has(ext)) {
+          pattern = basename(unquoted).replace(/\.\w+$/, '');
+        }
+        break;
+      }
+
+      // find -name / -iname: strip glob chars and extension from value
+      if (tok === 'find') { foundCmd = false; foundFileCmd = false; continue; }
+      if ((tok === '-name' || tok === '-iname') && tokens[i + 1]) {
+        const unquoted = tokens[i + 1].replace(/['"]/g, '');
+        const seg = basename(unquoted).replace(/\.\w+$/, '').replace(/[*?[\]{}]/g, '');
+        if (seg.length >= 3) { pattern = seg; }
+        break;
+      }
+    }
+  } else if (toolName === 'read') {
+    const raw = typeof input.path === 'string' ? input.path : null;
+    if (raw && CODE_EXTENSIONS.has(extname(raw))) {
+      pattern = basename(raw).replace(/\.\w+$/, '');
+    }
+  }
+
+  if (!pattern || pattern.length < 3) return null;
+  return pattern;
+}
+
+/**
+ * Extract up to `limit` unique file basenames (without extension) from
+ * grep-style output lines of the form "path/to/file.ext:lineno:content".
+ * Used to augment secondary context from search results.
+ */
+export function extractFilePatternsFromContent(
+  content: { type: string; text?: string }[],
+  limit = 2,
+): string[] {
+  const text = content.map(c => c.text ?? '').join('\n');
+  const seen = new Set<string>();
+  const results: string[] = [];
+  for (const line of text.split('\n')) {
+    // Match "some/path/File.ext:digits:" at the start of a line
+    const m = line.match(/^([^\n:]+\.\w+):\d+:/);
+    if (!m) continue;
+    const base = basename(m[1]).replace(/\.\w+$/, '');
+    if (base.length >= 3 && !seen.has(base)) {
+      seen.add(base);
+      results.push(base);
+    }
+    if (results.length >= limit) break;
+  }
+  return results;
+}
+
+/**
+ * Validate that a file path stays within cwd (path traversal guard).
+ * Returns the resolved absolute path, or null if it escapes cwd.
+ */
+export function safeResolvePath(file: string, cwd: string): string | null {
+  const resolved = resolve(cwd, file);
+  return resolved.startsWith(cwd + sep) || resolved === cwd ? resolved : null;
+}
+
+/**
+ * Spawn `gitnexus augment <pattern>` and return its output.
+ * gitnexus augment writes results to stderr (not stdout).
+ * Used by the tool_result hook — not by registered tools (those use mcp-client).
+ * Returns output trimmed and truncated to MAX_OUTPUT_CHARS, or "" on any error.
+ */
+export async function runAugment(pattern: string, cwd: string): Promise<string> {
+  return new Promise((resolve_) => {
+    // gitnexus augment writes results to stderr (not stdout)
+    let output = '';
+    let done = false;
+
+    const proc = spawn('gitnexus', ['augment', pattern], {
+      cwd,
+      stdio: ['ignore', 'ignore', 'pipe'],
+      env: spawnEnv,
+    });
+
+    const timer = setTimeout(() => {
+      if (!done) {
+        done = true;
+        proc.kill('SIGTERM');
+        resolve_('');
+      }
+    }, AUGMENT_TIMEOUT);
+
+    proc.stderr.on('data', (chunk: { toString(): string }) => { output += chunk.toString(); });
+
+    proc.on('close', (code: number | null) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      resolve_(code === 0 ? output.trim().slice(0, MAX_OUTPUT_CHARS) : '');
+    });
+
+    proc.on('error', () => {
+      if (!done) { done = true; clearTimeout(timer); resolve_(''); }
+    });
+  });
+}

package/src/index.ts

@@ -0,0 +1,260 @@
+import { spawn } from 'child_process';
+import type { ExtensionAPI, ExtensionContext } from '@mariozechner/pi-coding-agent';
+import { findGitNexusIndex, clearIndexCache, extractPattern, extractFilePatternsFromContent, runAugment, spawnEnv, updateSpawnEnv } from './gitnexus';
+import { mcpClient } from './mcp-client';
+import { registerTools } from './tools';
+
+const SEARCH_TOOLS = new Set(['grep', 'find', 'bash', 'read']);
+
+/** Resolve PATH from a login shell so nvm/fnm/volta binaries are visible. */
+async function resolveShellPath(): Promise<void> {
+  const shell = process.env.SHELL ?? '/bin/sh';
+  const path = await new Promise<string>((resolve_) => {
+    let out = '';
+    const proc = spawn(shell, ['-lc', 'echo $PATH'], { stdio: ['ignore', 'pipe', 'ignore'] });
+    proc.stdout.on('data', (d: { toString(): string }) => { out += d.toString(); });
+    proc.on('close', () => resolve_(out.trim()));
+    proc.on('error', () => resolve_(process.env.PATH ?? ''));
+  });
+  updateSpawnEnv({ ...process.env, PATH: path });
+}
+
+function probeGitNexusBinary(): Promise<boolean> {
+  return new Promise((resolve_) => {
+    const proc = spawn('gitnexus', ['--version'], { stdio: 'ignore', env: spawnEnv });
+    proc.on('close', (code: number | null) => resolve_(code === 0));
+    proc.on('error', () => resolve_(false));
+  });
+}
+
+/** Cached from session_start/session_switch — avoids re-probing on every /gitnexus status. */
+let binaryAvailable = false;
+
+/** Working directory of the current session — ctx.cwd in tool_result events may differ. */
+let sessionCwd = '';
+
+/** Controls whether the tool_result hook auto-appends graph context. Tools are unaffected. */
+let augmentEnabled = true;
+
+/** Number of successful augmentations this session. Shown in /gitnexus status. */
+let augmentHits = 0;
+
+/** Number of times the tool_result hook intercepted a search tool result this session. */
+let hookFires = 0;
+
+/**
+ * Patterns already augmented this session.
+ * Prevents the same symbol/file from being looked up repeatedly.
+ */
+const augmentedCache = new Set<string>();
+
+export default function(pi: ExtensionAPI) {
+  registerTools(pi);
+
+  // Append a one-liner so the agent understands graph context in search results.
+  pi.on('before_agent_start', async (event: { systemPrompt?: string }, ctx: ExtensionContext) => {
+    if (!findGitNexusIndex(ctx.cwd)) return;
+    if (event.systemPrompt == null) return;
+    return {
+      systemPrompt:
+        event.systemPrompt +
+        '\n\n[GitNexus active] Graph context will appear after search results. ' +
+        'Use gitnexus_query, gitnexus_context, gitnexus_impact, gitnexus_detect_changes, ' +
+        'gitnexus_list_repos for deeper analysis of call chains and execution flows. ' +
+        'If the index is stale after code changes, run /gitnexus analyze to rebuild it.',
+    };
+  });
+
+  // Core hook: mirrors the Claude Code PreToolUse integration.
+  // Intercepts grep/find/bash/read results, appends knowledge graph context.
+  pi.on('tool_result', async (event, ctx) => {
+    if (!augmentEnabled) return;
+    if (!SEARCH_TOOLS.has(event.toolName)) return;
+    hookFires++;
+    const cwd = sessionCwd || ctx.cwd;
+    if (!findGitNexusIndex(cwd)) return;
+
+    // Collect patterns: primary from input, secondary filenames from result content.
+    const primary = extractPattern(event.toolName, event.input);
+    const secondary = (event.toolName === 'grep' || event.toolName === 'bash')
+      ? extractFilePatternsFromContent(event.content)
+      : [];
+    const candidates = [...new Set([primary, ...secondary].filter((p): p is string => !!p))];
+
+    // Filter patterns already augmented this session.
+    const fresh = candidates.filter(p => !augmentedCache.has(p));
+    if (fresh.length === 0) return;
+
+    // Run up to 3 augments in parallel, merge results.
+    const toRun = fresh.slice(0, 3);
+    toRun.forEach(p => augmentedCache.add(p));
+    const results = await Promise.all(toRun.map(p => runAugment(p, cwd)));
+    const combined = results.filter(Boolean).join('\n\n');
+    if (!combined) return;
+
+    augmentHits++;
+    return {
+      content: [
+        ...event.content,
+        { type: 'text' as const, text: `\n\n[GitNexus]\n${combined}` },
+      ],
+    };
+  });
+
+  async function onSession(ctx: ExtensionContext) {
+    mcpClient.stop();
+    clearIndexCache();
+    augmentEnabled = true;
+    augmentHits = 0;
+    hookFires = 0;
+    augmentedCache.clear();
+    sessionCwd = ctx.cwd;
+    await resolveShellPath();
+
+    binaryAvailable = await probeGitNexusBinary();
+    if (!findGitNexusIndex(ctx.cwd)) return;
+
+    if (binaryAvailable) {
+      ctx.ui.notify(
+        'GitNexus: knowledge graph active — searches will be enriched automatically.',
+        'info',
+      );
+    } else {
+      ctx.ui.notify(
+        'GitNexus index found but gitnexus is not on PATH. Install: npm i -g gitnexus',
+        'warning',
+      );
+    }
+  }
+
+  pi.on('session_start',  (_event: unknown, ctx: ExtensionContext) => { void onSession(ctx); });
+  pi.on('session_switch', (_event: unknown, ctx: ExtensionContext) => { void onSession(ctx); });
+
+  pi.registerCommand('gitnexus', {
+    description: 'GitNexus knowledge graph. Type /gitnexus help for usage.',
+    handler: async (args: string, ctx: ExtensionContext) => {
+      const parts = args.trim().split(/\s+/);
+      const sub = parts[0] ?? '';
+      const rest = parts.slice(1).join(' ');
+
+      // /gitnexus  or  /gitnexus status
+      if (!sub || sub === 'status') {
+        if (!binaryAvailable) {
+          ctx.ui.notify('gitnexus is not installed. Install: npm i -g gitnexus', 'warning');
+          return;
+        }
+        if (!findGitNexusIndex(ctx.cwd)) {
+          ctx.ui.notify('No GitNexus index found. Run: /gitnexus analyze', 'info');
+          return;
+        }
+        const out = await new Promise<string>((resolve_) => {
+          let stdout = '';
+          const proc = spawn('gitnexus', ['status'], {
+            cwd: ctx.cwd,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            env: spawnEnv,
+          });
+          proc.stdout.on('data', (chunk: { toString(): string }) => { stdout += chunk.toString(); });
+          proc.on('close', () => resolve_(stdout.trim()));
+          proc.on('error', () => resolve_(''));
+        });
+        const augmentLine = augmentEnabled
+          ? `Auto-augment: on (${hookFires} intercepted, ${augmentHits} enriched this session)`
+          : 'Auto-augment: off';
+        ctx.ui.notify((out ? out + '\n' : '') + augmentLine, 'info');
+        return;
+      }
+
+      // /gitnexus help
+      if (sub === 'help') {
+        ctx.ui.notify(
+          '/gitnexus — GitNexus knowledge graph\n' +
+          '\n' +
+          'Commands:\n' +
+          '  /gitnexus             — show status\n' +
+          '  /gitnexus analyze     — index the codebase\n' +
+          '  /gitnexus on|off      — enable/disable auto-augment on searches\n' +
+          '  /gitnexus <pattern>   — manual graph lookup\n' +
+          '  /gitnexus query <q>   — search execution flows\n' +
+          '  /gitnexus context <n> — callers/callees of a symbol\n' +
+          '  /gitnexus impact <n>  — blast radius of a change\n' +
+          '\n' +
+          'Tools (always available to the agent):\n' +
+          '  gitnexus_list_repos, gitnexus_query, gitnexus_context,\n' +
+          '  gitnexus_impact, gitnexus_detect_changes',
+          'info',
+        );
+        return;
+      }
+
+      // /gitnexus on | off
+      if (sub === 'on' || sub === 'off') {
+        augmentEnabled = sub === 'on';
+        ctx.ui.notify(`GitNexus auto-augment ${augmentEnabled ? 'enabled' : 'disabled'}.`, 'info');
+        return;
+      }
+
+      // /gitnexus analyze
+      if (sub === 'analyze') {
+        if (!binaryAvailable) {
+          ctx.ui.notify('gitnexus is not installed. Install: npm i -g gitnexus', 'warning');
+          return;
+        }
+        augmentEnabled = false;
+        ctx.ui.notify('GitNexus: analyzing codebase, this may take a while…', 'info');
+        const exitCode = await new Promise<number | null>((resolve_) => {
+          const proc = spawn('gitnexus', ['analyze'], {
+            cwd: ctx.cwd,
+            stdio: 'ignore',
+            env: spawnEnv,
+          });
+          proc.on('close', resolve_);
+          proc.on('error', () => resolve_(null));
+        });
+        if (exitCode === 0) {
+          clearIndexCache();
+          augmentEnabled = true;
+          ctx.ui.notify('GitNexus: analysis complete. Knowledge graph ready.', 'info');
+        } else {
+          augmentEnabled = true;
+          ctx.ui.notify('GitNexus: analysis failed. Check the terminal for details.', 'error');
+        }
+        return;
+      }
+
+      // /gitnexus query <text>
+      if (sub === 'query') {
+        if (!rest) { ctx.ui.notify('Usage: /gitnexus query <text>', 'info'); return; }
+        const out = await mcpClient.callTool('query', { query: rest }, ctx.cwd);
+        if (out) pi.sendUserMessage(out, { deliverAs: 'followUp' });
+        else ctx.ui.notify('No results.', 'info');
+        return;
+      }
+
+      // /gitnexus context <name>
+      if (sub === 'context') {
+        if (!rest) { ctx.ui.notify('Usage: /gitnexus context <name>', 'info'); return; }
+        const out = await mcpClient.callTool('context', { name: rest }, ctx.cwd);
+        if (out) pi.sendUserMessage(out, { deliverAs: 'followUp' });
+        else ctx.ui.notify('No results.', 'info');
+        return;
+      }
+
+      // /gitnexus impact <name>
+      if (sub === 'impact') {
+        if (!rest) { ctx.ui.notify('Usage: /gitnexus impact <name>', 'info'); return; }
+        const out = await mcpClient.callTool('impact', { target: rest, direction: 'upstream' }, ctx.cwd);
+        if (out) pi.sendUserMessage(out, { deliverAs: 'followUp' });
+        else ctx.ui.notify('No results.', 'info');
+        return;
+      }
+
+      // /gitnexus <pattern>  — manual augment lookup
+      const pattern = sub + (rest ? ' ' + rest : '');
+      if (pattern.length < 3) { ctx.ui.notify('Pattern too short (min 3 chars).', 'info'); return; }
+      const out = await runAugment(pattern, ctx.cwd);
+      if (out) pi.sendUserMessage('[GitNexus]\n' + out, { deliverAs: 'followUp' });
+      else ctx.ui.notify('No graph context found for: ' + pattern, 'info');
+    },
+  });
+}

package/src/mcp-client.ts

@@ -0,0 +1,182 @@
+import { spawn, ChildProcess } from 'child_process';
+import { MAX_OUTPUT_CHARS, spawnEnv } from './gitnexus';
+
+interface JsonRpcResponse {
+  jsonrpc: '2.0';
+  id?: number;
+  result?: unknown;
+  error?: { code: number; message: string };
+}
+
+interface McpContent {
+  type: string;
+  text?: string;
+  isError?: boolean;
+}
+
+interface McpToolResult {
+  content: McpContent[];
+  isError?: boolean;
+}
+
+/**
+ * Thin stdio JSON-RPC 2.0 client for `gitnexus mcp`.
+ *
+ * Communication is exclusively over the spawned process's stdin/stdout pipe —
+ * no network socket, no port. Only our process can write to the pipe.
+ *
+ * The MCP process is started lazily on the first callTool() invocation and
+ * kept alive for the session lifetime. stop() terminates it; the next callTool()
+ * re-spawns with the new cwd.
+ */
+class GitNexusMcpClient {
+  private proc: ChildProcess | null = null;
+  private buffer = '';
+  private pending = new Map<number, { resolve: (raw: string) => void; reject: (e: Error) => void }>();
+  private nextId = 2; // id 1 is reserved for the initialize handshake
+  private startPromise: Promise<void> | null = null;
+
+  /**
+   * Lazily spawn `gitnexus mcp` and complete the MCP initialize handshake.
+   * Idempotent — concurrent calls await the same promise; only one process spawns.
+   */
+  private ensureStarted(cwd: string): Promise<void> {
+    if (this.proc) return Promise.resolve();
+    if (this.startPromise) return this.startPromise;
+
+    this.startPromise = new Promise<void>((resolve_, reject) => {
+      const proc = spawn('gitnexus', ['mcp'], {
+        cwd,
+        stdio: ['pipe', 'pipe', 'ignore'],
+        env: spawnEnv,
+      });
+
+      proc.on('error', (err) => {
+        this.startPromise = null;
+        reject(err);
+      });
+
+      proc.stdout!.setEncoding('utf8');
+      proc.stdout!.on('data', (chunk: string) => {
+        this.buffer += chunk;
+        const lines = this.buffer.split('\n');
+        this.buffer = lines.pop() ?? '';
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          try {
+            const msg = JSON.parse(line) as JsonRpcResponse;
+            if (msg.id !== undefined) {
+              const p = this.pending.get(msg.id);
+              if (p) { this.pending.delete(msg.id); p.resolve(line); }
+            }
+          } catch { /* ignore malformed lines */ }
+        }
+      });
+
+      proc.on('close', () => {
+        this.proc = null;
+        this.startPromise = null;
+        for (const p of this.pending.values()) {
+          p.reject(new Error('gitnexus mcp process exited'));
+        }
+        this.pending.clear();
+      });
+
+      // MCP initialize handshake
+      const initMsg = JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion: '2024-11-05',
+          capabilities: {},
+          clientInfo: { name: 'pi-gitnexus', version: '0.1.0' },
+        },
+      });
+
+      this.pending.set(1, {
+        resolve: () => {
+          proc.stdin!.write(
+            JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n'
+          );
+          this.proc = proc;
+          resolve_();
+        },
+        reject: (err) => {
+          this.startPromise = null;
+          reject(err);
+        },
+      });
+
+      proc.stdin!.write(initMsg + '\n');
+    });
+
+    return this.startPromise;
+  }
+
+  /**
+   * Call a gitnexus MCP tool and return its formatted text response.
+   * Starts the MCP process lazily if not already running.
+   * Returns "" on any error (graceful failure, same as the augment hook).
+   */
+  async callTool(name: string, args: Record<string, unknown>, cwd: string): Promise<string> {
+    try {
+      await this.ensureStarted(cwd);
+    } catch {
+      return '';
+    }
+
+    if (!this.proc) return '';
+
+    const id = this.nextId++;
+    return new Promise<string>((resolve_) => {
+      this.pending.set(id, {
+        resolve: (raw: string) => {
+          try {
+            const msg = JSON.parse(raw) as JsonRpcResponse;
+            if (msg.error) { resolve_(''); return; }
+            const result = msg.result as McpToolResult | undefined;
+            if (!result?.content || result.isError) { resolve_(''); return; }
+            const text = result.content
+              .filter((c) => c.type === 'text' && !c.isError && c.text)
+              .map((c) => c.text!)
+              .join('\n');
+            resolve_('[GitNexus]\n' + text.slice(0, MAX_OUTPUT_CHARS));
+          } catch {
+            resolve_('');
+          }
+        },
+        reject: () => resolve_(''),
+      });
+
+      const msg = JSON.stringify({
+        jsonrpc: '2.0',
+        id,
+        method: 'tools/call',
+        params: { name, arguments: args },
+      });
+
+      try {
+        this.proc!.stdin!.write(msg + '\n');
+      } catch {
+        this.pending.delete(id);
+        resolve_('');
+      }
+    });
+  }
+
+  /** Terminate the MCP process. Called on session_switch so the next session gets a fresh process. */
+  stop(): void {
+    if (this.proc) {
+      this.proc.kill('SIGTERM');
+      this.proc = null;
+    }
+    this.startPromise = null;
+    for (const p of this.pending.values()) {
+      p.reject(new Error('MCP client stopped'));
+    }
+    this.pending.clear();
+  }
+}
+
+export const mcpClient = new GitNexusMcpClient();

package/src/tools.ts

@@ -0,0 +1,113 @@
+import { Type } from '@sinclair/typebox';
+import type { ExtensionAPI } from '@mariozechner/pi-coding-agent';
+import { findGitNexusIndex, safeResolvePath } from './gitnexus';
+import { mcpClient } from './mcp-client';
+
+function text(msg: string) {
+  return { content: [{ type: 'text' as const, text: msg }], details: undefined };
+}
+
+const NO_INDEX = 'No GitNexus index found. Run: /gitnexus analyze';
+
+/**
+ * Register all GitNexus tools with pi.
+ * Called once from index.ts — this is the only way tools.ts accesses pi.
+ *
+ * TypeBox `default` values (e.g. `default: 5`) are JSON Schema annotations for
+ * agent documentation only. TypeBox does not inject them into params at runtime.
+ * Omitted optional params become undefined and are stripped by JSON.stringify,
+ * so the MCP server receives no value and applies its own defaults.
+ *
+ * Not exposed:
+ *   gitnexus_cypher  — raw graph queries; too open-ended, bypasses all validation
+ *   gitnexus_rename  — automated multi-file rename; high blast radius
+ */
+export function registerTools(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: 'gitnexus_list_repos',
+    label: 'GitNexus List Repos',
+    description: 'List all repositories indexed by GitNexus. Use first when multiple repos may be indexed.',
+    parameters: Type.Object({}),
+    execute: async (_id, _params, _signal, _onUpdate, ctx) => {
+      const out = await mcpClient.callTool('list_repos', {}, ctx.cwd);
+      return text(out || 'No indexed repositories found.');
+    },
+  });
+
+  pi.registerTool({
+    name: 'gitnexus_query',
+    label: 'GitNexus Query',
+    description: 'Search the knowledge graph for execution flows related to a concept or error.',
+    parameters: Type.Object({
+      query:           Type.String({ minLength: 1, maxLength: 200, pattern: '^[^-]' }),
+      task_context:    Type.Optional(Type.String({ minLength: 1, maxLength: 500 })),
+      goal:            Type.Optional(Type.String({ minLength: 1, maxLength: 500 })),
+      limit:           Type.Optional(Type.Integer({ minimum: 1, maximum: 100, default: 5 })),
+      include_content: Type.Optional(Type.Boolean()),
+    }),
+    execute: async (_id, params, _signal, _onUpdate, ctx) => {
+      if (!findGitNexusIndex(ctx.cwd)) return text(NO_INDEX);
+      const out = await mcpClient.callTool('query', params as Record<string, unknown>, ctx.cwd);
+      return text(out || 'No results.');
+    },
+  });
+
+  pi.registerTool({
+    name: 'gitnexus_context',
+    label: 'GitNexus Context',
+    description: '360-degree view of a code symbol: callers, callees, processes it participates in.',
+    parameters: Type.Object({
+      name:            Type.Optional(Type.String({ minLength: 1, maxLength: 200, pattern: '^[^-]' })),
+      uid:             Type.Optional(Type.String({ minLength: 1, maxLength: 200 })),
+      file:            Type.Optional(Type.String({ minLength: 1, maxLength: 500 })),
+      include_content: Type.Optional(Type.Boolean()),
+    }),
+    execute: async (_id, params, _signal, _onUpdate, ctx) => {
+      if (!findGitNexusIndex(ctx.cwd)) return text(NO_INDEX);
+      if (!params.name && !params.uid) return text('Provide either name or uid.');
+      // Validate file path server-side is handled by gitnexus, but guard here too.
+      let args: Record<string, unknown> = params as Record<string, unknown>;
+      if (params.file) {
+        const safe = safeResolvePath(params.file, ctx.cwd);
+        if (!safe) return text('Invalid file path.');
+        args = { ...params, file: safe };
+      }
+      const out = await mcpClient.callTool('context', args, ctx.cwd);
+      return text(out || 'No results.');
+    },
+  });
+
+  pi.registerTool({
+    name: 'gitnexus_impact',
+    label: 'GitNexus Impact',
+    description: 'Blast radius analysis: what breaks at each depth if you change a symbol.',
+    parameters: Type.Object({
+      target:        Type.String({ minLength: 1, maxLength: 200, pattern: '^[^-]' }),
+      direction:     Type.Optional(Type.Union([
+        Type.Literal('upstream'),
+        Type.Literal('downstream'),
+      ])),
+      depth:         Type.Optional(Type.Integer({ minimum: 1, maximum: 10, default: 3 })),
+      include_tests: Type.Optional(Type.Boolean()),
+    }),
+    execute: async (_id, params, _signal, _onUpdate, ctx) => {
+      if (!findGitNexusIndex(ctx.cwd)) return text(NO_INDEX);
+      const out = await mcpClient.callTool('impact', params as Record<string, unknown>, ctx.cwd);
+      return text(out || 'No results.');
+    },
+  });
+
+  pi.registerTool({
+    name: 'gitnexus_detect_changes',
+    label: 'GitNexus Detect Changes',
+    description: "Map a git diff to affected execution flows. Pass the output of `git diff HEAD` to find what breaks.",
+    parameters: Type.Object({
+      diff: Type.String({ minLength: 1, maxLength: 50_000 }),
+    }),
+    execute: async (_id, params, _signal, _onUpdate, ctx) => {
+      if (!findGitNexusIndex(ctx.cwd)) return text(NO_INDEX);
+      const out = await mcpClient.callTool('detect_changes', params as Record<string, unknown>, ctx.cwd);
+      return text(out || 'No affected flows detected.');
+    },
+  });
+}