@runecraft/graphify-pi

Minimal knowledge-graph extension for Pi

Query your codebase's knowledge graph from inside Pi — five tools, zero config, 83% fewer tokens.

---

What it does

@runecraft/graphify-pi wraps the graphify CLI as a Pi extension. It registers five tools that let your coding agent query, traverse, explain, and build a codebase knowledge graph instead of grepping raw files.

Tool	What it does
graphify_build	Build the knowledge graph from your codebase (run first)
graphify_query	BFS subgraph around concepts matching a natural-language question
graphify_path	Shortest path between two nodes (fuzzy match)
graphify_explain	Plain-language explanation of one node and its neighbors
graphify_update	Incrementally re-extract changed files (AST-only, no LLM cost)

Install

Via Pi (recommended)

pi install npm:@runecraft/graphify-pi

Manual with -e flag

Clone the repo and point Pi at the extension directly:

git clone https://github.com/runecraftai/pi-extensions.git
pi -e pi-extensions/packages/graphify-pi

Or for a single-session test:

pi -e /path/to/pi-extensions/packages/graphify-pi

As a project extension

Add to your project's .pi/extensions/ directory:

cp -r /path/to/pi-extensions/packages/graphify-pi ./graphify-pi
pi  # auto-discovers .pi/extensions/graphify-pi/

Requirements

• graphify CLI on PATH (or set GRAPHIFY_BIN)

  uv tool install graphifyy
  

• Node.js ≥ 20
• Pi with extension support

Note: graphify-pi requires the graphify CLI to function. If the CLI is not found, you'll see a warning at session start with installation instructions.

Configuration

All configuration via environment variables — no config files:

Variable	Default	Description
GRAPHIFY_BIN	graphify	Path to the graphify binary
GRAPHIFY_BUDGET	2000	Default token cap for graphify_query results
GRAPHIFY_STALE_COMMITS	1	Commits newer than graph before staleness notification
GRAPHIFY_MAX_OUTPUT	1048576 (1 MiB)	Max bytes from CLI stdout+stderr before truncation

How it works

session_start
  ├─ graphify CLI available?
  │   ├─ no  → warn "install with: uv tool install graphifyy"
  │   └─ yes → continue
  ├─ graphify-out/graph.json exists?
  │   ├─ yes → register 5 tools + check staleness
  │   └─ no  → register tools (user can run graphify_build)
  └─ staleness check: git rev-list --count HEAD --since=<mtime>
       └─ count > threshold → notify "graph is N commits stale"

Tools shell out to the graphify CLI with a 60s timeout and bounded output capture. No extraction logic is reimplemented — every call delegates to the pinned binary.

Quick start

1. Install graphify: uv tool install graphifyy
2. Install the extension: pi install npm:@runecraft/graphify-pi
3. Open Pi in your project
4. Run: graphify_build (or let the extension auto-detect an existing graph)
5. Query: graphify_query "how does authentication work?"

License

MIT — © 2026 Runecraft AI