pi-graphnav

CodeGraph-first code navigation for pi: the agent understands code through CodeGraph's symbol graph instead of grepping and reading file after file, without being told to.

A pi extension.

What it does

• Keeps the index current. At session start, in the background: codegraph init for a git repo without an index, a full codegraph index when the index is stale or was built by another CodeGraph version, codegraph sync for pending changes. An index a killed run left half-built is rebuilt (unless another process is indexing right now), and a failure on a stale lock gets codegraph unlock and one more try. While pi runs, the server's file watcher follows your edits.
• The codegraph_* tools (explore, search, node, callers, callees, impact, files, status) on one long-lived codegraph serve --mcp per project: no process start per call, and the watcher stays alive. Resilient, with arrow-resilience-kit: a server that dies under a call is restarted and the call retried once; after 3 failed calls in a row CodeGraph counts as unavailable for a minute, so calls fail fast and the gate stops sending the agent to it (status line: codegraph: unavailable).
• Steers symbol searches to CodeGraph. rg parseConfig, grep -rn UserService src, git grep, ag, ack and pi's grep tool with a symbol-like pattern are blocked once with the CodeGraph call that answers it (enforce), or run with that hint appended (nudge). Running the same command again is allowed: CodeGraph cannot answer everything. Searches for phrases, string literals or in docs and config (*.md, --type yaml, …) are never touched, nor symbols already looked up with CodeGraph. Searches a codemode script makes with literal tools.bash({ command }) / tools.grep({ pattern }) are gated the same way. A pattern only counts as a symbol when it has code shape (parseConfig, ParseConfig, start_scan, Foo::new) or symbol syntax (fn summary, summary(); plain words like summary, cache or Success are text. Before blocking, the gate asks the index (one codegraph_search, 2 s limit, fails open) and lets the search through when the index does not define the name. When it does, the block message already says where (path:line (kind)), so one blocked call still answers the question. A search inside named files (rg start_scan src/app.rs) is only nudged: the agent has already found the code.
• Nudges file-name lookups. fd UserService, find . -name '*ParseConfig*' and pi's find tool with a camelCase or snake_case name run, with a hint to codegraph_search (never blocked).
• Hints after blind reading. Reading several source files before any CodeGraph call adds one hint to use codegraph_explore; reading a whole source file over 400 lines adds one to fetch just the symbol with codegraph_node.
• Shows whether it helps. /codegraph status counts blocked searches, how many the agent answered with CodeGraph and how many it re-ran instead.
• Prompt guidance that stays the same every turn, so the prompt cache survives.

Needs the CodeGraph CLI: npm i -g @colbymchenry/codegraph. The project is the nearest directory with .codegraph/, else the git work tree; never your home directory.

Demos

A repo without an index: indexed in the background, then a symbol rg is blocked and the answer comes from codegraph_search and codegraph_callers.

nudge mode: the search runs, and its output points at CodeGraph.

The /codegraph command: status, mode, off/on, sync.

Recorded with VHS against a throw-away sample project and a scripted local model (just vhs, scripts/vhs.nu, examples/vhs/): a real pi with only this plugin.

Install

pi install npm:pi-graphnav

Use

Settings live in <pi agent dir>/codegraph.json (PI_CODING_AGENT_DIR, else ~/.pi/agent):

A project can override enabled, mode, autoInit, autoSync and readHintAfter for itself in <project>/.pi/codegraph.json (commit it to share), e.g. { "mode": "nudge" } for a repo full of generated code. A /codegraph command still wins for the session.

Replaces @vndv/pi-codegraph (same tool names): uninstall that one first.

Development

bun install
just check   # typecheck + tests (95% coverage gate) + pack check + nu script tests
just --list  # everything else: fuzz, audit, release, remotes

Layout:

Releases: just release patch bumps package.json, regenerates CHANGELOG.md with git-cliff, tags and pushes; the Release workflow publishes to npm (secret NPM_TOKEN).

License

MIT