@audsiui/pi-graphify

Five Pi tools over a graphify codebase knowledge graph — answer structural questions from the graph instead of grepping raw files.

The idea

"How does authentication work?" and "what calls this?" are graph questions. Answering them by reading files one by one burns tokens and context. graphify turns a codebase into a queryable knowledge graph with file:line citations and an honest EXTRACTED / INFERRED / AMBIGUOUS audit trail. This extension puts that graph behind native Pi tools so the agent reaches for it first.

The extension is a thin wrapper on purpose: no extraction logic, no daemon, no config files. All graph work happens through the graphify CLI and its own pipeline.

Requirements

• Pi with extension support (typechecked against 0.84)
• Node.js ≥ 20
• The graphify CLI: uv tool install graphifyy (avoid bare pip on Mac/Windows)

Install

pi install npm:@audsiui/pi-graphify

Or point Pi at a checkout:

pi -e /path/to/pi-graphify

The five tools

| Tool | Runs | Use it for | |------|------|------------| | graphify_query | graphify query "<q>" [--budget N] [--context C] [--dfs] [--graph P] | Broad "how does X work?" questions. BFS by default; --dfs to trace one specific chain. | | graphify_path | graphify path "A" "B" [--graph P] | How two nodes connect, hop by hop. Endpoints are fuzzy-matched by label. | | graphify_explain | graphify explain "<node>" [--graph P] | What one node is, where it lives, what it calls and is called by. | | graphify_update | graphify update | Incremental re-scan after edits. Code is AST-only — no LLM cost. | | graphify_build | — (returns the official pipeline guide) | First run, or full refresh after big refactors. Building is agent-driven per graphify's docs; the tool checks for an existing graphify-out/graph.json first and tells the agent to query instead of rebuilding when the graph is fresh (fast path). Builds are code-only: docs/papers/images/video are filtered out of the corpus and semantic extraction is skipped, so no API key is ever needed. |

Code-only graphs

The graph maps code relationships only. The build guide instructs the agent to filter the detected corpus to code files (dropping docs, papers, images, and video) and to skip semantic extraction entirely — builds stay deterministic and free, with no API key. graphify_update is code-only by design (graphify update re-extracts AST-only), so incremental refreshes match what was built.

Session behavior

On session_start the extension:

1. warns when the graphify CLI is missing,
2. registers the five tools lazily,
3. counts commits newer than graphify-out/graph.json via git rev-list and notifies when the graph is stale.

Every CLI call runs with a 60s timeout; output is truncated at 1 MiB, so a huge graph can never flood the context.

Configuration

All via environment variables — no config files.

| Variable | Default | Meaning | |----------|---------|---------| | GRAPHIFY_BIN | graphify | Path to the graphify binary | | GRAPHIFY_BUDGET | 2000 | Default token cap for graphify_query | | GRAPHIFY_STALE_COMMITS | 1 | Commits behind before the staleness notice | | GRAPHIFY_MAX_OUTPUT | 1048576 | Max CLI stdout+stderr bytes before truncation |

The bundled skill

skills/pi-graphify/SKILL.md ships a small skill, pi-graphify, that teaches the agent the official etiquette: query first when the graph exists (never rebuild unasked), answer only from graph output with file:line citations, rephrase with the graph's own vocabulary when results are noisy, run graphify_update after edits, and reserve full rebuilds for missing or stale graphs and big refactors.

Other repositories

Graphs are per-project but not locked to it: when a task needs code from another repository, graphify_build builds that repo's own graph (the guide directs graphify-out/ into the target repo), and the read tools accept a graph parameter pointing at any graph.json.

Purity guarantees

• Never registers anything. The extension does not run graphify install, so the official /graphify skill never lands in your assistant uninvited. The full build playbook ships inside the graphify package itself and is read on demand instead.
• Writes nothing itself. graphify only ever writes graphify-out/.
• No daemons, no watchers, no config files — env vars only.
• Every command the tools run is a documented one (graphify query, path, explain, update, --version).

License

MIT — © 2026 Audsiui