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