Treering

# <img src="docs/logo.svg" width="40" height="40" alt="" align="top"> Treering

English | [한국어](README.ko.md)

Treering draws a map of your codebase and keeps a copy of it for every commit, so you can see how the structure changed: which types started depending on each other last week, or when a class began to collect callers. It runs entirely on your machine and sends nothing over the network. It doesn't use an LLM, so the same code always produces the same graph.

![Opening a module and one of its namespaces in the schematic, coming back out, and the same sheet as a chip floor plan](docs/screenshots/demo.gif)

*Click a box to go inside it; the part you opened frames what it holds. Then back out, and the same sheet as a chip.*

![The blueprint as a schematic, compared with a month earlier: the Billing module is new and the web pages no longer call the database](docs/screenshots/schematic-compare.png)

*The sample project's modules as a schematic, compared with a month earlier. Green is new: a Billing module now implements the payment interface. Red dashed is gone: the web pages used to call the database directly.*

| | |
|---|---|
| ![The map, comparing two snapshots](docs/screenshots/map-compare.png) | ![The blueprint as a drawing](docs/screenshots/blueprint.png) |
| **Map.** Modules as bubbles and the calls between them. New lines are green, broken ones red. | **Blueprint.** One level as boxes in tiers, each with its role and what the others use it for. |
| ![Inside one module, drawn as a hierarchical sheet](docs/screenshots/schematic-inside.png) | ![One class with its members, and the types around it](docs/screenshots/class.png) |
| **Inside a module.** The module you opened frames what it holds; wires cross its edge at sheet ports. | **One class.** Its fields and methods, the types it works with, and which member ties them. |
| ![The chip floor plan, regions sized by code](docs/screenshots/chip.png) | |
| **Chip.** Where the weight is: each region as big as its code, libraries as pads on the edge. | |

All of these are the sample project that comes with Treering (`treering sample`), a small made-up shop.

Treering is still in development, and the database format may change between releases. The design notes are in [treering-plan.md](treering-plan.md) (in Korean).

## Install

Windows (PowerShell):

```powershell
irm https://raw.githubusercontent.com/RedholeTechnologies/Treering/main/install.ps1 | iex
```

Linux (x86-64):

```bash
curl -fsSL https://raw.githubusercontent.com/RedholeTechnologies/Treering/main/install.sh | sh
```

Each script downloads the latest build from [Releases](https://github.com/RedholeTechnologies/Treering/releases), checks it against the published checksum, and puts `treering` on your PATH. On Windows it also adds Treering to the Start menu. Neither needs administrator rights, and running a script again updates Treering. If you'd rather not run a script, download the zip or tarball from Releases and unpack it anywhere.

Then run `treering`, or open it from the Start menu. It starts the server and opens http://127.0.0.1:7377 in your browser. If Treering is already running, it only opens the browser.

To look around before importing anything, choose **Or look around a sample project first** on the first screen. It adds `acme-shop`, a small made-up online shop with a month of history. `treering sample` adds it from the command line.

## Install the indexers

Treering doesn't parse source code itself. It reads [SCIP](https://github.com/sourcegraph/scip) indexes, which each language's indexer produces. Install the indexers for the languages you use:

```bash
dotnet tool install --global scip-dotnet       # C#
npm install -g @sourcegraph/scip-typescript    # TypeScript and JavaScript
npm install -g @sourcegraph/scip-python        # Python
```

## Import a repository

```bash
treering import /path/to/repo
treering serve
```

`import` looks at which languages the repository contains and runs each indexer with the flags it needs. For C# it indexes the solution at the root, or each project if there's no solution. For TypeScript it indexes each topmost `package.json`, and for Python each `pyproject.toml`. The graph is stored in your user folder, never inside the repository, and `treering projects` lists what you've imported.

`treering serve` opens the map at http://127.0.0.1:7377. Without a database argument it serves every imported project, and you can switch between them in the menu at the top of the page.

You can also import from the page. Open the project menu, choose **Import…**, then **Choose a folder…**. The server opens your system's folder picker (Explorer on Windows, the standard dialog on macOS, zenity or kdialog on Linux), because a browser won't give a page the full path of a folder. You can type the path instead. The import starts when you pick a folder, and the dialog shows each indexer as it runs. If one fails, it tells you why and what to try.

The import and folder endpoints only accept JSON requests sent by the page itself, so another site open in your browser can't start an import or open a window.

## Read the map

The map shows modules, namespaces and types as nodes, and the references between them as edges.

- Click a node to go inside it. The node you entered stays on screen as a ring around its contents. Click empty space, right-click the ring, or press Esc to go back up, and the map marks the node you just left.
- Colour shows whose code it is: each of your own modules has a colour, and libraries are grey. Size shows how much a node is used.
- The **Shape** menu lays out the same graph five ways: Constellation, Orbit, Ring, Layers and Tree. Layers stacks dependencies from top to bottom and keeps cycles together. Tree shows what contains what, one branch at a time.
- The side panel describes what you're inside, or the type you clicked: its members, what it injects and where it's injected, what it implements, its callers and what it calls. Each name in the panel links to that node.
- Press `/` or `Ctrl+K` to search. Picking a result takes you to where it lives.
- **At** and **Compare** show the graph at one snapshot, or the edges added and removed between two.
- **Scope** switches between everything and **Our code**. A symbol counts as yours when the index contains its definition, so libraries drop out without guessing from names. On Acme.Shop this cuts 38 modules to 4 and 829 types to 401.
- **Theme** offers Light, Dark, Slate, Skyfall and Obsidian, and **Language** switches between English and Korean.
- If your system is set to reduce motion, the decorative animation stops.

## Keep it up to date

```bash
treering update /path/to/repo
treering watch /path/to/repo       # every 10 minutes
treering watch /path/to/repo 30    # every 30 minutes
```

`update` re-indexes only the projects whose files changed. Each changed file goes to its nearest project (`.csproj`, `package.json`, or `pyproject.toml` and `setup.py`) and that language's indexer, so a repository with several languages updates each part with its own tool. If an indexer is missing, Treering prints the command that installs it.

`watch` runs `update` on a timer and adds a snapshot only when something changed, so the history fills in while you work. It starts from the commit recorded in the last snapshot, so you can stop and restart it without losing anything, and it counts uncommitted changes as well as commits.

You usually don't need to run `watch` yourself: `treering serve` does the same for every imported project while it runs. Every 10 minutes it re-indexes what changed and adds a snapshot, and if you're looking at the latest snapshot the page moves to the new one by itself. A re-index that leaves the graph as it was adds no snapshot. Turn it off with `--no-watch` or under **Settings** on the page, change the period with `--watch-minutes N`, and pick another port with `--port N`.

## Work with indexes directly

You can run an indexer yourself and load its output. For C#:

```bash
scip-dotnet index YourSolution.slnx --allow-global-symbol-definitions --output index.scip
treering load index.scip graph.db
treering serve graph.db
treering callers graph.db OrderRepository
treering map graph.db type --own
```

Always pass `--allow-global-symbol-definitions` to scip-dotnet. Without it, symbols don't carry their package name, and once you index projects separately or add snapshots, one symbol turns into several. In one test that recorded 6,784 symbols as added and 6,790 as removed.

To compare over time, load more snapshots:

```bash
treering snap index-new.scip graph.db 1
treering diff graph.db 0 1
treering growth graph.db InvoiceModel
```

`diff` lists the dependencies added and removed between two snapshots, and `growth` shows when a type's callers increased.

## Use it from an agent

```bash
treering mcp
```

This runs a Model Context Protocol (MCP) server over stdio for the projects you've imported. It has six tools: `list_projects`, `find_symbol`, `callers_of`, `subgraph`, `changed_since` and `snapshots`. Each tool takes a `project` (a name or id from `list_projects`); left empty, it asks the most recently imported one. They run the same queries as the page, with the same size limits. When a result would be too large, the response says what was left out so the agent can narrow the question and ask again. `treering mcp graph.db` answers about that one database only.

To add it to Claude Code:

```bash
claude mcp add treering -- treering mcp
```

In other hosts, the command is `treering` with the argument `mcp`. Each release also carries MCP bundles (`treering-win-x64.mcpb`, `treering-linux-x64.mcpb`) for hosts that install MCPB in one step, and is published to the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.RedholeTechnologies/treering`.

## Performance

On Acme.Shop (4 projects, 632 `.cs` files):

| Step | Result |
|---|---|
| Indexing (scip-dotnet) | 89s |
| Loading into the gr