@xynogen/pix-graph

Pi extension — native code knowledge graph (TS/JS exact, other languages via ast-grep)

Packages

Package details

extensionskill

Install @xynogen/pix-graph from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@xynogen/pix-graph
Package
@xynogen/pix-graph
Version
0.4.4
Published
Nov 4, 2026
Downloads
1,121/mo · 451/wk
Author
xynogen
License
MIT
Types
extension, skill
Size
176.8 KB
Dependencies
4 dependencies · 3 peers
Pi manifest JSON
{
  "skills": [
    "./skills"
  ],
  "extensions": [
    "src/extension.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pix-graph

Native-TS code knowledge graph — extract, cluster, analyze, and query a codebase without Python or an external service. TS/JS is parsed with the TypeScript compiler API into a graph of files and symbols. Imports resolve to real files (relative paths, tsconfig paths/baseUrl aliases, and workspace packages through package.json exports; require, import() and vi.mock/jest.mock/mock.module strings count as imports, so tests that mock a module show in impact), and calls edges follow import bindings and re-exports. Communities are found with Louvain over file-level dependencies; questions are answered by BFS/DFS traversal over the graph, or by ranking whole modules for architecture questions.

Ships three ways: a model-callable graph tool, a CLI, and a library. Standalone/opt-in — not bundled by pix-core, so the one recurring tool schema is only present when you install it.

graph tool

One tool, four actions:

Call Effect
graph(action:"build", path?) (Re)build/update the graph from source into .pi/graph/. Run again after edits to refresh.
graph(action:"query", question, dfs?) Lexical search: match keywords against symbol/file names, then traverse. Ties between seeds break by PageRank. BFS (default) for broad context, dfs:true to trace a path.
graph(action:"query", question, scope:"global") Rank whole modules (workspace packages) for architecture questions. Returns each module's summary and evidence card.
graph(action:"impact", question, path?) Reverse dependencies: who calls, uses (types, constants) or imports a symbol or file, transitively (3 hops, 60 nodes). Class methods and properties are their own Class.member nodes, so impact can target one method. Ends with affected files and tests. Above 25 direct dependents, the result folds them per package with counts and still lists every test file. path narrows an ambiguous name.
graph(action:"summarize") List up to 5 modules whose summary is missing or stale, with their evidence cards and a token estimate.
graph(action:"summarize", module, summary) Store a summary written by the agent. It must cite the module's card.

When sources changed after the last build, query and impact rebuild the graph first (cached, about 2 s) and say so. If that rebuild fails, they answer from the old graph and add a stale note.

Summaries live in .pi/graph/summaries.json, keyed by module, evidence hash, model, and prompt version. The tool never calls a model itself: the session model writes each summary, and the result shows which model did it. An unchanged rebuild leaves every summary current, so a repeat run has no work.

pix-nudge also drops a one-line reminder to prefer graph(action:"query") over grepping when .pi/graph/graph.json exists (it also detects a legacy graphify-out/graph.json). Output lives under the gitignored .pi/ dir.

CLI

pix-graph build [path] [--out DIR] [--root DIR]   # extract + cluster + analyze
pix-graph query "<question>" [--graph FILE] [--dfs] [--depth N]
pix-graph path "<from>" "<to>" [--graph FILE]      # shortest path between nodes

build writes into --out (default .pi/graph/):

Output Description
graph.json Full graph: nodes (with package), links, community assignments
graph.cleaned.json Graph that query reads, after validation; communities are computed on this graph
GRAPH_REPORT.md Named communities, package boundaries (imports, calls, APIs, file:line sites), unresolved internal imports, god nodes, surprising connections
graph.html Interactive view of graph.cleaned.json: community colors, search, node details. Open it with /graph.

Library

import { buildCodeGraph, query, analyzeGraph } from "@xynogen/pix-graph";

const result = buildCodeGraph("src", process.cwd(), ".pi/graph");
// → { nodes, links, communities, outputDir }
Export Purpose
collectFiles, extract Walk a tree and parse TS/JS into { nodes, links, unresolved }
buildGraph, cluster, communityLabels, cohesionScore, scoreAll Assemble, Louvain community detection, deterministic names
godNodes, surprisingConnections Graph analysis
query, impact, shortestPath Traversal over a built graph
renderGraphReport, boundaries Human-readable report and package boundary cards
analyzeGraph, renderPatternReport Validate/clean an existing graph + extract repeated patterns (also at @xynogen/pix-graph/analyzer)
renderGraphHtml Interactive HTML view of a graph
buildCodeGraph Full pipeline orchestrator

The graph JSON schema (nodes/links/hyperedges, EXTRACTED/INFERRED confidence) is compatible with external graphify — a graph built by either tool works with the other's query.

Scope ceilings

  • Other languages are coarser than TS/JS. TS/JS use the TypeScript compiler (import bindings, re-exports). Python, Go, Rust, Java, C/C++, Ruby and the rest of the ast-grep languages go through the shared engine in @xynogen/pix-runtime/ast: definitions plus calls edges (INFERRED) only when exactly one file defines the called name. No import edges yet. A missing grammar is installed once after the user agrees; until then the build reports that language as skipped.
  • Louvain, not Leiden. Leiden needs the native graspologic library. Upgrade path: add a Leiden refinement pass over the Louvain communities.
  • Lexical query seeds, no embeddings. Global scope gains meaning only from stored summaries. Upgrade path: BM25 or a similarity model if recall proves weak.
  • String references other than module specifiers are invisible. Route URLs, redirects, and config keys are plain strings, not edges. Use grep for those.
  • Code only. For docs, PDFs, images, or video, use external graphify.

Install

pi install npm:@xynogen/pix-graph

Standalone and opt-in. @xynogen/pix-core does not bundle it. You run it on demand. Its graph tool schema loads only when you install it.

Full distro

This package is part of Pix. The installer sets up Pi and the full distro. See Install for the notes for each OS.

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.sh | sh
# Windows
irm https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.ps1 | iex

License

MIT