Graphy

Created by Matt Hartigan, 2026.

Feed it your repo. See how the code actually connects.

Graphy compiles Python, TypeScript, and JavaScript into a graph you can click through. See what depends on a function, follow a dependency cycle, or investigate a module sitting on its own. Recorded conversations can link to the code they name, so you can find the earlier discussion before changing it. Coding agents can query both through MCP.

Explore the live maps · Try the messy repo · Setup and commands

Install

pip install --upgrade 'graphyos[typescript]>=0.2.8'
cd /path/to/your/repo
graphy showcase . --no-provision

Open .graphy/showcase/index.html for the 2D explorer, with a link to the 3D view. Version 0.2.8 includes both. No account or model API key needed.

The package is graphyos; the command and Python import are graphy. Python 3.10+. Omit [typescript] for Python-only repos. Add [estate,typescript] for DuckDB queries over compiled packages. --no-provision reads source without running the repo's installer.

Use

graphy eat      --repo <abs> --site-packages <abs> [--package <name>]   # the bolt-on: everything below, into <repo>/.graphy
graphy smash    --package <name> --site-packages <abs> --out <abs>      # mint a package and its import ring
graphy init     --tenant <descriptor> --root <abs> --data-home <abs> …   # declare a tenant: every path absolute, nothing ambient
graphy converge --tenant <descriptor> --tenant-id <name> [--resolve]     # the seam per shard pair; resolve text labels through scope
graphy build    --tenant <descriptor> --tenant-id <name>                 # compile the store; emit the parquet when duckdb is present
graphy walk     --tenant <descriptor> --tenant-id <name> --seed <id> --target <id>
graphy estate   --tenant <descriptor> --tenant-id <name> --sql "<over adj, nodes and walks>"
graphy traversals --tenant <descriptor> --tenant-id <name> [--replay]
graphy descend  <symbol> --tenant <descriptor> --tenant-id <name>   # the callees down to the primitives, every package crossing
graphy blast    <symbol> …                                           # the dependents against the edges, own shard and ring
graphy explain  <symbol> …                                           # the record, the docs, the tests that reach it, the journal page
graphy mcp      --tenant <descriptor> --tenant-id <name>              # the five doors as MCP tools on stdio, for Claude Code / Cursor / any client
graphy shell install --repo <abs>       # the hooks and the walk-before-edit gate, into an eaten repo — see graphy/shell/README.md
graphy check    --tenant <descriptor> --tenant-id <name>                 # read-only audit: exit 0 healthy, 1 a verdict, 2 never ran
graphy fanout   --graph-dir <shard> --out <dir>                          # the fan-out, with a receipt
graphy harness  --repo <abs> [--tenant <descriptor> --tenant-id <name>] [--corpus <pkg>]  # the hub: GRAPH.md, arms, drawings, walk receipts

The four pillars

json   JSON is the cheapest machine currency
keys   we own the join keys, in one central registry
ast    AST is hierarchy, not magic — anything with rules becomes AST
lens   the whole world is traversable through our lens

Two laws worth stating up front

No ambient fallback. An absent tenant refuses. The engine never defaults to a tenant, a root, or a data home. Every one of them is a declared field on the descriptor, and an absent one is an error rather than a guess. Two tenants run in one process without either being able to read the other's data.

No model ever decides an edge. Every edge is one of exactly three things: structural (built from the syntax tree), a wormhole (the same literal is a node id in two or more graphs — free by construction), or a label resolved through the scope that binds it (the module's own definitions and imports, self, super). Similarity alone parks forever and never graduates; a name match is never an edge.

Vocabulary is declared per producer

The Graph IR is the boundary — typed node, edge, provenance and evidence records. AST is one producer among several, never the contract. Each adapter declares its own vocabulary and they mutually refuse: validate_graph(nodes, edges, Vocabulary(...)) returns a count or raises.

License

Apache 2.0 — see LICENSE. Attribution propagates through NOTICE (Apache §4(d)). "Graphy" and "GraphyOS" are trademarks; the license grants no trademark rights (§6).