Graph X

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.

Related MCP server: LiLBrain

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:

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

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:

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

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