<p align="center">
  <img src="docs/logo.svg" width="130" alt="Graph X logo">
</p>

<h1 align="center">Graph X</h1>

<p align="center">
  A local knowledge graph for any project — built to make Claude Code (or any MCP client)<br>
  dramatically cheaper and smarter on your codebase.
</p>

<p align="center">
  <img src="https://img.shields.io/badge/license-MIT-4fc59a" alt="MIT license">
  <img src="https://img.shields.io/badge/node-%E2%89%A522.5-9d8cff" alt="Node 22.5+">
  <img src="https://img.shields.io/badge/dependencies-zero-d97757" alt="Zero dependencies">
  <img src="https://img.shields.io/badge/MCP%20tools-7-5eb3d6" alt="7 MCP tools">
</p>

<p align="center">
  <b>English</b> · <a href="README.ru.md">Русский</a> · <a href="README.az.md">Azərbaycanca</a> · <a href="README.tr.md">Türkçe</a> · <a href="README.es.md">Español</a>
</p>

---

Graph X automatically indexes every file in a folder, extracts the relationships between them — imports, doc links, tests, semantic similarity — and stores them in a local SQLite graph. That graph is then served two ways: to **Claude Code** through 7 MCP tools, and to **you** as an interactive, live-updating force-directed graph in the browser.

**Why it exists:** without a graph, Claude re-reads your files from scratch every session — tens of thousands of tokens just to "learn" the project. With Graph X, Claude queries the graph first (a full project map costs ~600 tokens, a file summary ~200) and only opens the 2–3 files that actually matter. Typical result: **8–10× fewer tokens per session**, faster answers, better focus.

This is the tool's own repository rendered by its own `snapshot` command:

![Graph X rendering its own repository](docs/graph.svg)

*(Formerly "bilik-qrafi" — Azerbaijani for "knowledge graph".)*

## Highlights

- **Zero dependencies.** No `npm install`, ever. One Node.js binary, built-in `node:sqlite` and `node:zlib`. The MCP protocol, PDF/DOCX text extraction, TF-IDF semantic search, HTTP/SSE server and graph physics are all hand-rolled in ~2,500 lines.
- **Incremental & live.** Hash-based indexing (a no-change re-index takes ~10 ms on this repo); a file watcher re-indexes on save and pushes updates to the browser over SSE.
- **Understands more than code.** JS/TS, Python, PHP, Vue/Svelte, HTML, CSS — plus Markdown links, `[[wiki-links]]`, and full text inside **PDF and DOCX** files.
- **Finds hidden structure.** TF-IDF semantic edges connect files that talk about the same thing even when no import or link exists between them.
- **Claude-native.** One `setup` command registers the MCP server, teaches Claude the "query the graph before reading files" rule, and lets Claude render the graph for you on request.
- **Neumorphic UI.** Soft light/dark chrome, keyboard-first (`/` to search, `Esc` to reset), impact mode that shows what breaks if a file changes.

## Quickstart

Requirements: Node.js ≥ 22.5 on your PATH, **or** a portable `node.exe` dropped at `.tools/node/node.exe` (no admin rights needed — grab it from [nodejs.org/dist](https://nodejs.org/dist/latest-v24.x/win-x64/)).

```
graphx index .        # build the graph for the current folder
graphx stats .        # print the project map in the terminal
graphx serve .        # interactive graph at http://localhost:7341
```

Windows: `graphx.cmd` (or double-click `graph.cmd` to start the server and open the browser). macOS/Linux: `./graphx.sh`.

## Try the demo

The repo ships with a small but realistic project — [`demo/shop-api`](demo/shop-api) — an Express e-commerce API with an auth stack, routes, a database layer, payments, docs and tests. Its graph looks like this:

![The demo project's knowledge graph](docs/demo-graph.svg)

Notice what the graph surfaces instantly: `docs/architecture.md` and `src/auth/login.js` are the most connected nodes, tests attach to what they cover with their own edge kind, and dashed lines mark documentation and semantic links. Explore it live:

```
graphx serve demo/shop-api --port 7345
```

## Use it with Claude Code

One command attaches Graph X to any project:

```
graphx setup C:\path\to\your-project
```

It writes four things into the target project (and nothing else), then runs the first index:

| File | Purpose |
|---|---|
| `.mcp.json` | Registers the `graph-x` MCP server for that folder |
| `CLAUDE.md` | Appends the rule: *query the graph before reading files* |
| `.claude/launch.json` | Lets Claude start the graph UI itself when you ask to see it |
| `.gitignore` | Excludes the `.graph/` database |

Restart your Claude Code session in that folder and Claude gains seven tools:

| Tool | What it does | ≈Tokens |
|---|---|---|
| `project_map` | Whole-project map: counts, folders, hub files with summaries | 600 |
| `find_relevant` | Semantic + structural search, ranked with summaries | 300–1k |
| `get_summary` | One file's summary, exports, dependencies — without reading it | 200 |
| `get_connections` | Every inbound/outbound edge of a file | 300 |
| `impact_analysis` | Reverse-dependency BFS: what breaks if this file changes | 500 |
| `graph_snapshot` | Renders the graph to SVG so Claude can show it in chat | 100 |
| `reindex` | Incremental re-scan after big refactors | 100 |

A typical session then looks like: *"where is authentication handled?"* → Claude calls `project_map`, then `find_relevant("authentication")`, then reads only the one or two files that matter. The graph keeps itself fresh — any tool call re-checks the filesystem if the index is older than 60 seconds.

Full walkthrough: [docs/SETUP.md](docs/SETUP.md) · Tool reference: [docs/MCP-TOOLS.md](docs/MCP-TOOLS.md)

## The graph UI

Node = file (color = type, size = connections). Line = relationship (dashed = doc/semantic). Drag nodes, pan and zoom, click a node for its summary, connections and token stats. `/` focuses search, type chips filter, and **impact mode** paints the clay-colored wave of files that transitively depend on the one you click. The sun/moon button flips the neumorphic chrome between light and dark.

## Adding data

There is no import step — **drop files into the indexed folder**:

| Kind | Formats | What gets extracted |
|---|---|---|
| Code | JS/TS/JSX/TSX, Python, **PHP**, Vue, Svelte, HTML, CSS/SCSS… | imports/exports, functions, classes → structural edges |
| Notes | `.md` (links + `[[wiki-links]]`), `.txt`, `.rst` | links, headings → doc edges |
| Documents | **`.pdf`, `.docx`** | full text via the built-in zero-dep extractor → searchable, semantically linked |
| Config | `package.json`, `.env`, YAML/TOML/JSON | dependencies, entry points |

While `serve` runs, changes appear in the browser within ~2 seconds. Scanned (image-only) PDFs are indexed as metadata-only nodes — no OCR yet.

For a personal knowledge base, point it at a vault folder: `graphx setup C:\Vault && graphx serve C:\Vault --port 7342`. Every folder gets its own independent `.graph/graph.db`.

## Index a GitHub repository

No git required — Graph X downloads the archive over HTTPS and unpacks it with its own zip reader:

```
graphx github vercel/next.js              # owner/name (default branch)
graphx github owner/repo#dev  my-folder   # branch + custom target
```

The repo arrives already indexed and Claude-ready (`setup` runs automatically).

## Settings

Optional per-project `graphx.config.json` (template: `graphx config --init`):

```json
{
  "port": 7341,
  "ignoreDirs": ["legacy"],
  "ignoreFiles": ["*.generated.ts"],
  "semanticThreshold": 0.36,
  "staleSeconds": 60
}
```

This repository uses one to keep `demo/` out of its own graph. All keys: [docs/CONFIGURATION.md](docs/CONFIGURATION.md).

## CLI reference

| Command | Description |
|---|---|
| `graphx index [path] [--force]` | Incremental index (hash-based); `--force` rebuilds everything |
| `graphx stats [path]` | Project map in the terminal |
| `graphx serve [path] [--port n]` | Web UI + live watch |
| `graphx mcp [path]` | MCP server over stdio (used by Claude Code) |
| `graphx setup [path]` | Attach to a project (MCP + rules + launch config + first index) |
| `graphx snapshot [path] [--out f] [--max n]` | Render the graph to a standalone SVG |
| `graphx github <repo> [dir]` | Download a GitHub repo and attach the graph |
| `graphx config [path] [--init]` | Show effective settings / create a config file |

## Architecture

```
files → watcher (hash diff) → parsers (imports/links) + PDF/DOCX extractor + TF-IDF
                                     ↓
                        SQLite  .graph/graph.db  (files / edges / meta)
                           ↓                        ↓
                    MCP server (stdio)        HTTP + SSE server
                           ↓                        ↓
                      Claude Code            browser graph UI
```

Module-by-module notes live in [CLAUDE.md](CLAUDE.md).

## Limitations & roadmap

Parsing is regex-based (tree-sitter planned) — string literals can occasionally leak keywords. Summaries are structural (LLM summaries planned). Semantic search is TF-IDF (neural embeddings planned). No OCR for scanned PDFs; XLSX/PPTX not indexed yet.

## License

[MIT](LICENSE)