pi-gitnexus-plus

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

Built on tintinweb/pi-gitnexus, this fork extends the original with multi-transport support, a broader tool surface, and Docker server management.

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's different from pi-gitnexus

| | pi-gitnexus | pi-gitnexus-plus | | --------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | Transport | Stdio only (local gitnexus mcp process) | Stdio + Streamable HTTP | | MCP client | Handrolled JSON-RPC 2.0 | Official @modelcontextprotocol/sdk | | Agent tools | 7 | 14 | | MCP resources | Not supported | All 10 resource types via gitnexus_read_resource | | Docker/remote | Not supported | Full support — health checks, server-side analyze, job polling | | API analysis | — | Route maps, shape checks, API impact reports | | Multi-repo | — | Group management and contract registry sync | | Server management | — | REST client for /api/analyze, /api/repos, /api/health, /api/info |

Everything from the original is preserved — auto-augment, session caching, skills, settings, all 7 original tools with identical names and schemas.

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>

Requirements

You need one of the following:

• Local CLI: gitnexus >= 1.4.8 on PATH (e.g. npm i -g gitnexus), OR
• HTTP server: A GitNexus server accessible over HTTP (e.g. running in Docker at http://localhost:4747/api/mcp)

The extension never installs anything automatically. If your local CLI setup differs from the default, use /gitnexus settings to set a custom command (e.g. npx gitnexus@latest).

Getting started

Option A: Local CLI (stdio transport)

1. Install the extension: pi install npm:pi-gitnexus-plus
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

Option B: HTTP server (e.g. Docker)

1. Install the extension: pi install npm:pi-gitnexus-plus
2. Start the GitNexus server (e.g. docker run -p 4747:4747 -v /path/to/repos:/workspace gitnexus/server)
3. Start pi with the server flag: pi --gitnexus-server http://localhost:4747/api/mcp
4. Run /gitnexus analyze to trigger server-side indexing
5. Done — all tools and auto-augment work over HTTP

Or configure permanently via /gitnexus settings → MCP transport → http, then set the Server URL.

Agent tools

14 tools are registered in pi and always available to the agent:

Core tools

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

API & route analysis

| Tool | Description | | ---------------------- | ------------------------------------------------------------ | | gitnexus_route_map | Show API route mappings: consumers, handlers, middleware | | gitnexus_tool_map | Show MCP/RPC tool definitions and handler locations | | gitnexus_shape_check | Check API response shapes against consumer property accesses | | gitnexus_api_impact | Pre-change impact report for an API route handler |

Multi-repo & resources

| Tool | Description | | ------------------------ | ------------------------------------------------------------------------------------- | | gitnexus_group_list | List configured repository groups | | gitnexus_group_sync | Rebuild the contract registry for a repository group | | gitnexus_read_resource | Read a GitNexus MCP resource by URI (repo context, clusters, processes, schema, etc.) |

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 (local CLI or server-side) | | /gitnexus analyze <url> | Clone and index a git repo by URL (HTTP mode only) | | /gitnexus on / /gitnexus off | Enable/disable auto-augment (tools unaffected) | | /gitnexus settings | Open the settings panel | | /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 |

CLI flags

| Flag | Description | | -------------------------- | ------------------------------------------------------------------------------------------------- | | --gitnexus-cmd <command> | Override the gitnexus command (e.g. npx gitnexus@latest) | | --gitnexus-server <url> | Connect to a GitNexus HTTP server (e.g. http://localhost:4747/api/mcp). Overrides saved config. |

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.

Settings

Open /gitnexus settings or /gitnexus → Settings to configure:

| Setting | Description | Default | | ----------------------- | -------------------------------------------------------------- | ------------ | | Auto-augment | Enrich search results with graph context | on | | Augment timeout | Max wait time for graph augmentation (seconds) | 8 | | Max augments per result | Patterns to augment in parallel per search result | 3 | | Max secondary patterns | File-based patterns extracted from grep/bash output | 2 | | MCP idle timeout | Stop the MCP process after inactivity (seconds; off = never) | 600 | | GitNexus command | Shell command to invoke gitnexus (stdio mode) | gitnexus | | MCP transport | stdio (local CLI) or http (remote server) | stdio | | Server URL | MCP endpoint URL (HTTP mode) | — | | Auth token | Bearer token for server authentication (HTTP mode) | — | | Workspace directory | Path inside Docker container where repos are mounted | /workspace |

How it works

Auto-augment

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 looks them up in the knowledge graph 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.

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.

MCP transport

Tools communicate with GitNexus via the MCP SDK (@modelcontextprotocol/sdk). Two transports are supported:

• Stdio (default) — spawns gitnexus mcp as a child process. Communication over stdin/stdout pipe. Lazily started on first tool call, stopped after 10 minutes of inactivity (configurable). No network socket, no port.
• Streamable HTTP — connects to a GitNexus HTTP server (e.g. running in Docker). Uses the MCP Streamable HTTP protocol with automatic session management. Configure via --gitnexus-server flag or /gitnexus settings.

In HTTP mode, auto-augment routes through the query tool instead of the CLI subprocess. All 14 tools and MCP resources work over both transports.

Session lifecycle

On session start/switch, the extension resolves the full shell PATH through $SHELL (picking up nvm/fnm/volta without depending on a specific user shell), probes the binary (stdio) or server health (HTTP), and notifies accordingly. The MCP connection is restarted with the new working directory.

Docker server management

In HTTP mode, the extension communicates with the GitNexus server's REST API for operations that don't fit the MCP tool/resource model:

| Endpoint | Purpose | | ------------------------- | --------------------------------------------------------------- | | GET /api/health | Server health check (used during session start) | | GET /api/info | Server version and context (shown by /gitnexus status) | | GET /api/repos | List indexed repositories | | POST /api/analyze | Trigger server-side analysis (accepts path, url, or name) | | GET /api/analyze/:jobId | Poll analysis job progress |

/gitnexus analyze in HTTP mode constructs the container path from your workspace directory setting and the current directory name, or you can pass a git URL directly: /gitnexus analyze https://github.com/user/repo.git.

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.
• 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 setups the extension automatically passes the current repo root path to MCP tools, but every tool also accepts an explicit repo override.
• gitnexus_rename and gitnexus_cypher are exposed intentionally; use gitnexus_rename with dry_run first because it can propose multi-file edits.
• gitnexus_read_resource can read any MCP resource by URI — use gitnexus://repos to discover available repos, or gitnexus://repo/{name}/schema to get the graph schema for Cypher queries.
• Markdown files (.md, .mdx) participate in augmentation alongside code files when GitNexus has indexed them.
• The enrichment is appended to the tool result the agent receives — files on disk and raw tool outputs are never modified.

Attribution

This project is a fork of tintinweb/pi-gitnexus — the original GitNexus integration for pi. The core auto-augment hook, session lifecycle, skills framework, and the first 7 tools originate from that project.

License

MIT — see LICENSE for details.

This extension 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.