graphyos

# graphy

[![ci](https://github.com/omnislash157/graphyos/actions/workflows/ci.yml/badge.svg)](https://github.com/omnislash157/graphyos/actions/workflows/ci.yml)


**Bolt it onto a repo and it eats the whole thing.** One command mints your package and every
package it imports into a walkable substrate, resolves who calls what through the code's own
scope, compiles it into a store, lays parquet beside every shard, and audits the result. Then you
ask it things: does A reach B, what crosses from my code into that dependency, who calls this
class across the whole ring. No model decides an edge. Every answer is a walk over structure,
and every walk is a query, never a load — the build reads the shard JSON once into the store,
and no walk reads a file again.

Created by Matt Hartigan, 2026. Apache 2.0.

## The thirty-second demo

One blast-radius question on FastAPI, three ways, every answer scored against the store's own
list of dependents. Run on this box; the full output is in `RECON.md` §20.

```text
`iterate_in_threadpool` in Starlette is about to change its signature. What in FastAPI breaks, and through which call chain?

┌────────────────────────────────┬──────────┬───────────┬──────────┬────────────┐
│ way                            │ seconds  │ tokens in │ tok out  │ dependents │
├────────────────────────────────┼──────────┼───────────┼──────────┼────────────┤
│ graphy alone, no model         │     0.00 │         0 │        0 │   5/5      │
│ claude-haiku-4-5 + graphy MCP  │     14.8 │     48266 │     1286 │   5/5      │
│ claude-opus-5 + 270 KB source  │     26.5 │    103171 │     2108 │   5/5      │
└────────────────────────────────┴──────────┴───────────┴──────────┴────────────┘
```

A cold small model with graphy's five walk tools (`draw` came after this run) and nothing else names the same five functions, with
the chain, as a frontier model handed the three right source files by hand. The store alone does
it in a millisecond.

```bash
bash engine/tenants/fastapi/rebuild.sh                                   # the FastAPI tenant, from the vendored shard
.venv/bin/python engine/tenants/fastapi/demo.py --runner claude-code     # on your Claude Code login
ANTHROPIC_API_KEY=… .venv/bin/python engine/tenants/fastapi/demo.py      # or the SDK (pip install anthropic)
```

Point any MCP client at the same server: Claude Code reads it from this repo's `.mcp.json`;
anywhere else, `bash engine/tenants/fastapi/mcp.sh` on stdio, or `graphy mcp --tenant … --tenant-id …`
over any eaten repo. Six tools: `hunt` · `descend` · `blast` · `walk` · `draw` · `explain`.

Over your own repo, no pointer to write: `graphy eat .` once, then the Claude Code plugin at
[`.claude-plugin/plugin.json`](.claude-plugin/plugin.json) runs `graphy mcp --repo "${CLAUDE_PROJECT_DIR}"` —
the server reads `.graphy/tenant.json` under the project root and the package name from the ring
receipt eat left, and refuses by name when the repo has not been eaten. The same argv is the MCP
registry's entry, [`server.json`](server.json) (`uvx graphyos mcp --repo <repo>`).

```bash
claude plugin marketplace add omnislash157/graphyos    # the repo is the marketplace (.claude-plugin/marketplace.json) …
claude plugin install graphy@graphyos                  # … and the plugin; inside Claude Code the same two as /plugin …
claude --plugin-dir /path/to/graphyos                   # or a checkout, no marketplace: the checkout is the plugin
```

## The page, one line

```bash
uvx --from 'graphyos[typescript]' graphy showcase .     # no venv, no install — the page at .graphy/showcase/index.html
```

`uvx` is [uv](https://github.com/astral-sh/uv)'s runner: it makes the venv, installs `graphyos`
into it and runs `graphy showcase` over the repo you are in — the modules drawn, the pillars the
walk proposes, the ring, the MCP block, three questions. Run on this box from a scratch venv
holding nothing but `uv` (`RECON.md` §86). This is the drawing it makes of graphy itself, from
graphy's own store — [`docs/pillars.svg`](docs/pillars.svg), written by the graphy tenant's rebuild,
re-rendered and compared byte for byte in the gate, never drawn by hand:

![graphy's pillars, drawn by graphy from its own store](docs/pillars.svg)

## Install, then eat — two lines

```bash
pip install 'graphyos[estate,typescript]'     # PyPI: graphyos 0.2.3 — the extras are optional
cd /path/to/your/repo && graphy eat .        # a repo with several packages: graphy eat . --package <name>
graphy showcase .                            # the page: .graphy/showcase/index.html — open it in a browser
```

The distribution is `graphyos`; everything you type after install is `graphy`. Python 3.10+ on
Linux and macOS; on Windows, through WSL — `eat` resolves a venv on either layout by `sysconfig`,
but the hooks, `shell install` and the MCP pointer are bash, and the store lock is a named no-op
without `fcntl`.
`[estate]` is DuckDB for the parquet estate; without it every JSON door still works and the build
says `CONTAINER SKIPPED` instead of pretending. `[typescript]` is tree-sitter for the TypeScript
and JavaScript producer.

`eat` provisions the repo's own dependencies beside it (a venv with `pip install <repo>`, or
`npm install` for a `package.json` repo — printed, and a repo that will not install is minted
alone and the line says so), mints the package and every package it imports, resolves the labels
through scope, compiles the store, audits it, and ends with the three things you do next: the
MCP block to paste into Claude Code or Cursor, the drawing, three questions.

**Eating a repo you do not trust runs its build.** `pip install <repo>` runs that repo's build
backend on your machine, and `npm install` its dependencies' installs (scripts off). For a
stranger's repo, `graphy eat . --no-provision` (and `graphy showcase <url> --no-provision`)
runs nothing of theirs: the package is minted from its source with an empty ring, every import
left unresolved by name, no venv, no pip, no npm. `--site-packages` names an install you
already have and skips the provisioning.

**What it reads today.** Python, through the standard library's own parser; TypeScript (with
TSX) and JavaScript (ESM and CommonJS), through tree-sitter. Nothing else yet: a language is a
producer, a resolver and a locator, and those are the ones that exist.

`eat` prints every step as it lands and ends with what you do next:

```text
MINT OK: httpx 538 nodes / 2548 edges -> …/.graphy/substrate/httpx_graph
MINT OK: httpcore 539 nodes / 2251 edges -> …/.graphy/substrate/httpcore_graph
…
RING: 7 shard(s) · stdlib skipped 62 · unresolved brotli, click, h2, … -> …/.graphy/substrate/ring.json
RESOLVE OK: httpx 1658 label(s) -> … edge(s) (import … · local … · reexport … · self … · super …)
BUILD OK: compiled 2522 nodes / … edges -> …/.graphy/substrate/.mesh_store_….sqlite
CONTAINER PENDING: 7 shard(s) — graphy estate emits them on the first ask, graphy container --emit writes them now
CHECK OK: descriptor valid; store fresh; journal readable for all declared graphs; container fresh for 0/7 shard(s), 7 pending until the estate asks
EAT OK: httpx + 6 ring shard(s) -> /path/to/repo/.graphy
  the tenant:  --tenant /path/to/repo/.graphy/tenant.json --tenant-id httpx
  a walk:      graphy walk --tenant … --tenant-id httpx --seed httpx://module/httpx --target certifi://module/certifi
  the estate:  graphy estate --tenant … --tenant-id httpx
  the walks:   graphy traversals --tenant … --tenant-id httpx [--replay]
```

```bash
# 3. does A reach B — across packages, on the literal
graphy walk --tenant /path/to/repo/.graphy/tenant.json --tenant-id httpx \
    --seed httpx://module/httpx --target certifi://module/certifi
#   WALK PATH: hops=2 steps=httpx://module/httpx -> httpx://module/httpx._config -> certifi://module/certifi
#   TRAVERSAL: source=live reads=15 stored=…/.graphy/substrate/traversals/<generation>/<seed>.parquet
# run it again: source=store reads=0 — the walk is kept as rows; a walk from another seed that
# crosses this one splices through it, and after the repo moves `graphy traversals --replay`
# names the hops that no longer hold

# 4. the whole ring as one SQL view: adj(corpus, src, dst, edge_type, attrs, dst_repr, src_repr) and nodes(corpus, id, …)
graphy estate --tenant /path/to/repo/.graphy/tenant.json --tenant-id httpx \
    --sql "SELECT a.corpus, n.corpus, count(*) FROM adj a JOIN nodes n ON a.dst = n.id WHERE a.corpus <> n.corpus GROUP BY 1, 2 ORDER BY 3 DESC"
#   httpx_graph  httpcore_graph  …        ESTATE OK: 9 row(s) over 7 shard(s) in 5.8 ms

# 5. is it still true — the store against the repo's HEAD, the parquet against the shards
graphy check --tenant /path/to/repo/.graphy/tenant.json --tenant-id httpx
```

Everything lands in `<repo>/.graphy/`, which ignores itself (your `git status` stays clean) and
is rebuilt from the previous shards every time. It holds a shard per package in the ring, so a
big application eats big: a company repo with numpy, networkx and livekit in its ring lands 165
shards and about a gigabyte beside the repo, in a hundred seconds (15,456 files parsed). A repo with several importable packages
is refused by name before anything is installed — `graphy eat . --package <name>` picks one.
Node ids are `<package>://<module|class|func|method>/<dotted>`.

## Or let the script do all five

```bash
bash quickstart.sh https://github.com/encode/httpx.git
#   … GRAPHY_QUICKSTART_OK: httpx eaten in 5.9s -> staging/quickstart/httpx/.graphy
```

Clones the repo, installs its dependencies into a venv of their own, eats it, runs the estate
query and the walk, and prints the done token with the time. That line is the proof this README
is true on the machine it ran on; `RECON.md` §16 records the last run.

## What an edge is, and is not

Every edge is one of three things: **structural** (from the syntax tree — imports, contains,
inherits, decorates, calls), a **wormhole** (the same literal is a node id in two shards, free by
co