Graph X

<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:

(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).

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 — an Express e-commerce API with an auth stack, routes, a database layer, payments, docs and tests. Its graph looks like this:

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 · Tool reference: 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):

{
  "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.

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.

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