pi-gograph

Gograph integration for pi — AST-aware Go code navigation as native LLM tools.

What it does

Gograph builds a compact graph of your Go project's packages, symbols, calls, routes, and tests. This extension exposes gograph's capabilities as native pi tools, so the LLM can navigate your Go codebase with fewer raw file reads and better accuracy.

Key benefits:

• gograph_plan — pre-edit safety check in ONE call (replaces 5-8 separate tool calls)
• gograph_review — post-edit review in ONE call
• gograph_explain — architectural narrative in ONE call
• gograph_context replaces 4-5 grep/cat calls in one shot
• gograph_implementers reliably finds interface implementations
• gograph_endpoint traces HTTP handlers from route to SQL

Prerequisites

• pi installed
• gograph installed (the extension can auto-install it via /gograph-setup)

Installation

pi install npm:pi-gograph

Note: Use pi install, not npm install. The pi install command registers the extension in pi's settings so it auto-activates in Go projects.

Or install manually by copying to your extensions directory:

git clone https://github.com/yinloo-ola/pi-gograph.git
cp -r pi-gograph ~/.pi/agent/extensions/

Usage

The extension activates automatically in Go projects (detected by go.mod or *.go files). You'll see a status indicator in pi's footer:

• 📦 gograph: run /gograph-setup — gograph not installed
• gograph: run /gograph-build — installed but no index
• gograph ✓ (gograph 0.3.1) — ready (version shown when available)
• gograph: rebuilding index in background... — a branch/HEAD change was detected and a refresh is running without blocking other work

First time setup

If gograph is not installed:

/gograph-setup

This will:

1. Try to install gograph via Homebrew, falling back to go install if brew fails
2. Build the initial index

If gograph is already installed, /gograph-setup will offer to upgrade to the latest version.

Rebuild index

After significant code changes:

/gograph-build

Or with precise mode (type-checked, slower):

/gograph-build --precise

Check status

/gograph-status

Automatic background refresh

When you switch git branches or otherwise change the tracked HEAD, pi-gograph will refresh the index in the background the next time you use a gograph tool or /gograph-status. Existing operations keep using the last built index until the refresh finishes.

Tools

Primary tools (one per task)

| Tool | Purpose | |------|--------| | gograph_build | Build/rebuild the AST index | | gograph_query | Search for symbols by name | | gograph_context | Full context bundle (source + callers + callees + tests). Supports --uncommitted for all modified symbols. | | gograph_implementers | Find structs implementing an interface. Supports --test-only for mock/test implementations. | | gograph_endpoint | HTTP handler → SQL vertical slice | | gograph_plan | Pre-edit change plan: callers, tests, blast radius, SQL/env exposure. Supports --uncommitted and --with-context. | | gograph_review | Post-edit review: test coverage, complexity, broken interfaces. Supports --uncommitted. | | gograph_explain | Architectural narrative for any symbol in one call |

Generic tool (gograph)

For advanced queries not covered by primary tools. Uses subcommand parameter:

| Subcommand | Purpose | |-----------|--------| | callers | Find callers of a function. Supports --depth N. | | callees | Find callees of a function. Supports --depth N. | | source | Extract source of one symbol | | fields | All fields of a struct | | impact | Blast radius analysis. Supports --uncommitted. | | path | Shortest call chain between two symbols | | returnusage | How callers consume a function's return value | | errorflow | Trace error string from definition to handlers | | changes | Find symbols in changed files. Use flags: "--git main". | | check | Verify uncommitted changes. Supports --uncommitted. | | focus | Targeted context for a package | | stats | Index health summary: version, timestamp, counts | | dependents | Find packages that import a given package | | usages | Find all references to a type in signatures and fields | | literals | Find all struct literal initialization sites |

Development

git clone https://github.com/yinloo-ola/pi-gograph.git
cd pi-gograph
npm install
npm test

License

MIT