pi-gitnexus

GitNexus knowledge graph integration for pi. Enriches every search, file read, and symbol lookup with call chains, callers/callees, and execution flows — automatically.

https://github.com/user-attachments/assets/49e61667-f508-4d22-abad-05241e414664

The graph view in the demo is from gitnexus-web and is not part of this extension.

What it does

When the agent reads a file or runs a search (grep, find, bash, read_many), 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

Agent calls read_many([api.ts, db.ts, router.ts])
  → file contents returned normally
  → [GitNexus] appended with per-file labeled sections:
      ### api.ts
      <call graph context for api>
      ### db.ts
      <call graph context for db>

Seven tools are also registered directly in pi — the agent can use them explicitly for deeper analysis without any setup.

Requirements

• gitnexus >= 1.4.8 available as gitnexus on PATH (e.g. npm i -g gitnexus)
• A GitNexus index in your project: run /gitnexus analyze

The extension never installs anything automatically. It assumes gitnexus is on PATH. If your setup differs, use /gitnexus settings to set a custom command (e.g. npx gitnexus@latest).

Getting started

1. Install the extension: pi install npm:pi-gitnexus
2. Install gitnexus: npm i -g gitnexus
3. Open your project in pi
4. Run /gitnexus analyze to build the knowledge graph
5. Done — file reads and searches are now enriched automatically

What triggers augmentation

| Tool | Pattern used | |---|---| | grep | Longest identifier literal extracted from the search pattern | | bash with grep/rg | First non-flag argument after grep/rg (quote-aware, pipe-safe) | | bash with cat/head/tail | Filename of the target file (quote-aware) | | bash with find | Value of -name/-iname | | find | Glob pattern basename | | read | Filename of the file being read (indexed code/docs files only) | | read_many | Each indexed code/docs file in the batch (up to 5), labeled per-file in output | | Any grep/bash result | Filenames extracted from result lines (path/file.ts:line:) |

Each tool result augments up to 3 patterns in parallel (up to 5 for read_many). Patterns already augmented this session are skipped.

Commands

| Command | Description | |---|---| | /gitnexus | Open the main menu (status, Analyze, Settings, Help) | | /gitnexus status | 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 settings | Open the settings panel (auto-augment, timeout, limits, command) | | /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 | Analyze staged/unstaged/all/compare git changes and affected execution flows | | gitnexus_rename | Coordinated multi-file rename preview/apply through the knowledge graph | | gitnexus_cypher | Execute raw Cypher queries against the graph |

Skills

The extension bundles 5 workflow skills that guide the agent through common tasks:

| Skill | When to use | |---|---| | /skill:gitnexus-exploring | Understand architecture, trace execution flows, explore unfamiliar code | | /skill:gitnexus-debugging | Debug a bug, trace an error, find why something fails | | /skill:gitnexus-pr-review | Review a PR, assess merge risk, check blast radius | | /skill:gitnexus-refactoring | Rename, extract, split, or restructure code safely | | /skill:gitnexus-impact-analysis | Know what breaks before changing something |

Skills are loaded on-demand — only the description is in context until the agent or user invokes one.

How it works

Auto-augment hook — fires after every grep/find/bash/read/read_many tool result. Extracts up to 3 patterns (primary from input, secondary filenames from result content) and calls gitnexus augment for each in parallel. Regex patterns are parsed to extract the longest identifier-like literal; bash commands are tokenized with quote and pipe boundary awareness. Results are wrapped in --- delimiters and appended to the tool result. For read_many, each file in the batch gets its own labeled section so the agent knows exactly which context belongs to which file.

Session dedup cache — each symbol or filename is augmented at most once per session (case-insensitive). Patterns with results are cached in augmentedCache; patterns that returned empty are tracked in a separate emptyCache to prevent unbounded retries while still allowing retries after an index rebuild (both caches clear on session reset and after a successful /gitnexus analyze).

MCP client — tools (list_repos, query, context, impact, detect_changes, rename, cypher) communicate with gitnexus mcp over a stdio pipe. The process is spawned lazily on the first tool call and stopped after 10 minutes of inactivity (configurable via /gitnexus settings → MCP idle timeout; set to off to keep it alive for the whole session). No network socket, no port.

Session lifecycle — on session start/switch, the extension resolves the full shell PATH through /bin/sh (picking up nvm/fnm/volta without depending on a user shell like nushell), 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 itself is published under the PolyForm Noncommercial License — commercial use requires a separate agreement with its author. Install and use gitnexus in accordance with its license terms.

Notes

• Tested with gitnexus 1.4.8. Older versions may have incompatible MCP schemas.
• The extension never runs gitnexus analyze automatically — indexing is always user-initiated via /gitnexus analyze.
• The index is a static snapshot. Re-run /gitnexus analyze after significant code changes. The agent will suggest this when the index appears stale.
• In multi-repo GitNexus setups the extension automatically passes the current repo root path to MCP tools, but every tool also accepts an explicit repo override.
• gitnexus_detect_changes follows the current MCP API: use scope (unstaged, staged, all, or compare) and optional base_ref instead of pasting raw diffs.
• Markdown files (.md, .mdx) participate in augmentation alongside code files when GitNexus has indexed them.
• gitnexus_rename and gitnexus_cypher are exposed intentionally; use gitnexus_rename with dry_run first because it can propose multi-file edits.
• The enrichment is appended to the tool result the agent receives — files on disk and raw tool outputs are never modified.