# graphy

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

Models will build you a slop cathedral overnight. Graphy gives you the floor plan
and connects it to what you said while building it.

Graphy compiles Python, TypeScript, and JavaScript into a graph you can click through.
It also links recorded conversations to the code they name. See what depends on a function,
then find the earlier discussion before changing it. Your coding agent can query both
through MCP, across sessions.

[![ci](https://github.com/omnislash157/graphyos/actions/workflows/ci.yml/badge.svg)](https://github.com/omnislash157/graphyos/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/graphyos)](https://pypi.org/project/graphyos/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/graphyos/)
[![License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)

[![Graphy's 2D explorer showing six modules connected to utils in the included messy-code example](docs/atlas.png)](examples/messy-repo/README.md)

*Actual Graphy output from the [messy example below](examples/messy-repo/README.md).
Click a module to light up its dependencies and dependents. Search, pan, zoom, or switch to 3D.*

**[Explore the live maps](https://graphy-os.com)** · **[Try the messy repo](examples/messy-repo/README.md)** · **[Setup and commands](docs/guide.md)**

## Point it at your code

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

Open **`.graphy/showcase/index.html`** in your browser. That's your map.
The page links to the 3D explorer too. No account or model API key needed.

Version `0.2.8` includes the explorer shown above. The package is `graphyos`; the command
is `graphy`. Python 3.10+ on Linux, macOS, and Windows. Omit `[typescript]` for Python-only
repos.

`--no-provision` reads source without running the repo's installer. Drop it on a trusted
repo to include dependencies Graphy can install and resolve.
[Several packages in one checkout?](docs/guide.md#several-packages-in-one-checkout)

## Show me the mess

The gallery has FastAPI, httpx, and other well-kept projects. Most of us also have a
`utils.py` that does too much, half a migration, and a feature someone forgot to wire up.

[`examples/messy-repo`](examples/messy-repo/README.md) is a tiny, deliberately messy Python app.
The source ships here. **Graphy drew this from it:**

![Unfiltered Graphy map: checkout, payments, and notifications form a cycle; six modules depend on utils; legacy_export only connects to legacy_store; recommendations stands alone](docs/messy-repo.svg)

| What catches your eye | What to investigate |
|---|---|
| `checkout → payments → notifications → checkout` | Why does sending a receipt depend on checkout? |
| Six modules point at `utils` | Which callers would a helper change affect? |
| `recommendations` sits alone | The function exists. Who was supposed to call it? |
| `legacy_export → legacy_store` is a separate island | Is this still an entry point, or a migration leftover? |

The picture includes every recorded module dependency, including single links and isolated
modules. The default showcase filters lighter connections; the
[walkthrough](examples/messy-repo/README.md) shows how to open this unfiltered map and click it.

An island is a place to investigate. Dynamic loading and external entry points can escape
static analysis. The isolated `tangle` node here is just the empty package initializer.

Try it from this checkout:

```bash
graphy showcase examples/messy-repo --no-provision
```

Then ask a concrete question:

```bash
graphy blast tangle.utils.money \
  --tenant examples/messy-repo/.graphy/tenant.json --tenant-id tangle
```

That helper reaches **six dependent functions** across checkout, payments, reporting,
admin, and the API. Graphy prints the callers and the chain that leads to each one.
[Run the queries yourself.](examples/messy-repo/README.md#ask-the-graph)

## Come back tomorrow and know why

The map shows what changing `utils.money` would affect. The earlier conversation can
tell you why you left it alone:

> Keep tangle.utils.money at two decimals. Checkout and reporting both use it.
> Split their formatting before changing the shared helper.

That's the **fictional conversation included in the demo**. Graphy connects its explicit
mention of the function to the same node its callers reach:

```mermaid
flowchart LR
    caller["checkout.submit"] -->|calls| helper["utils.money"]
    session["Earlier conversation"] -->|mentions| helper
```

`blast` shows the callers and recorded mentions. `history --symbol` finds the sessions
that discussed the function; the original words stay in Markdown. Session hooks preserve
those conversations and bring the latest context into the next session.

**The code map tells you what connects. The linked history helps you recover why.**
Try both together from this checkout, after installing its engine:

```bash
python examples/messy-repo/memory_demo.py
```

It builds a separate temporary repo, finds the six dependent functions and two recorded
messages, and prints the sample conversation. [How the demo works →](examples/messy-repo/README.md#follow-the-code-back-to-the-conversation)

## Give your agent the same map

After generating your map, add this to `.mcp.json` for Claude Code or your client's MCP settings.
Replace the path with your repo's absolute path:

```json
{
  "mcpServers": {
    "graphy": {
      "command": "graphy",
      "args": ["mcp", "--repo", "/absolute/path/to/your/repo"]
    }
  }
}
```

Ask it: **“What depends on this function?”**, **“How does this request reach the database?”**,
or **“What did we discuss about this function last time?”**

`hunt` finds symbols. `blast` follows dependents. `descend` follows dependencies.
`walk` finds a path. `draw` makes the picture. `explain` and `history` add context.
The same tools work in your terminal.

To capture that history in your own Git repo, install the session hooks:

```bash
graphy shell install --repo /absolute/path/to/your/repo
```

As sessions accumulate, refresh their links into the graph with `graphy history --remint`
and your tenant arguments. [Capture, recovery, and history setup →](docs/guide.md#connect-conversations-to-code)

## What's underneath

A compiler: source → syntax trees → resolved connections → a queryable store.
The visuals and the agent tools read that store. No model chooses an edge, and you don't
need embeddings to find a caller. Unresolved connections stay unresolved.

The Python core has no required third-party Python dependencies. `[typescript]` adds
tree-sitter; `[estate]` adds DuckDB for SQL across the compiled packages.

[How connections work, setup options, and more commands](docs/guide.md) ·
[Worked FastAPI example](engine/tenants/fastapi/FASTAPI.md) ·
[Graphy drawn by Graphy](docs/pillars.svg) ·
[Measured runs](RECON.md) · [Changelog](CHANGELOG.md) ·
[What the files in this repo do](docs/guide.md#repository-layout)

Created by Matt Hartigan, 2026. [Apache 2.0](LICENSE).

<!-- mcp-name: io.github.omnislash157/graphyos -->