Docs / Start

How LLMGRAPH is put together

The two packages, the shared engine and the limits it keeps, the programs that run when your agent asks, the files on your disk, the environment variables, and how to see and stop what is running.

On this pageThe packages that are ours The chain, from your agent to the checkers The shared engine The governor What runs, who started it, when it ends Which versions, and how to see them Files on your disk Environment variables Processes: see them, stop one Two sessions on one project A clean install

The packages that are ours

Two npm packages, only these:

Package	What it is
`llmgraph-mcp`	The launcher. A small Node program. It is what `npx -y llmgraph-mcp` runs.
`@brainfoods-studio/win32-x64`	The engine for Windows x64. The launcher starts it. Do not install it on its own.

Other projects with a similar name are not ours: @llmgraph/mcp-server, n8n-nodes-llmgraph and @masol/llmgraph. Retired: the V1 packages llmgraph-in and trishul-mcp, and any llmgraph-mcp below 0.4.0. If you have one of them, remove it.

The beta runs on Windows x64 only. On any other machine the launcher prints one line saying so and stops.

The chain, from your agent to the checkers

your agent
  -> npx -y llmgraph-mcp
     -> launcher           bin/llmgraph.js            (Node)
        -> session         engine/llmgraph.exe serve  (one per agent session)
           -> engine       engine/llmgraph-engine.exe (one for the whole computer)
              -> Python checker      tools/ty/ty.exe
              -> TypeScript checker  Node + tools/ts_bridge.mjs + tools/typescript
              -> parse workers       engine/llmgraph.exe --parse-worker

Everything below launcher sits inside the one platform package, next to each other: engine/, tools/, notices/ and release/. The launcher is a separate package. It finds the platform package by name, checks that the two versions match, and starts engine/llmgraph.exe with your arguments. It passes your agent's input to that program and its output back, so your agent talks to it as if it had started the engine itself. The launcher owns that input: when your agent closes its input, or the launcher itself is gone, the session sees the end of its input and shuts down.

The session is thin. The reading, the saved indexes and the checkers belong to the shared engine, described in the next section.

The shared engine

One llmgraph-engine.exe serves every agent session of your Windows account on the computer. Its file description reads "LLMGRAPH engine (local code analysis)".

It starts on demand. An agent session starts it the first time it needs one. LLMGRAPH registers nothing that starts it when the computer boots.
Sessions share it. Two agents on the same project, or on two projects, use the one engine. Each session keeps its own answer memory, so one session is never told "unchanged since your last answer" about an answer it did not see. Only your own Windows account can reach it, over a local pipe on your computer. It opens no network port.
**ps shows it.** The line starts llmgraph-engine.exe, then its process id, when it started, how long until it leaves, its memory and processor time, the projects it has open and the sessions attached to it. See Processes.
**stop ends it.** stop and stop --all end the engine. stop --repo <folder> closes that one project and leaves the engine and its other projects running.
It leaves by itself. After 20 minutes with no session attached it shuts down, closes every saved index cleanly and removes its files. A project that has had no session for 20 minutes is closed before that, and the engine reopens it when a session asks again. The two times are the settings engine.idle_minutes and engine.project_idle_minutes.
One engine per session, as in 0.4.1. Set idle_minutes = 0 under [engine] in the settings file (%APPDATA%\llmgraph\config.toml) and every session runs its own engine, as before. The engine reads the setting again each time a session attaches.
If the engine ends under a session, the session starts a new one and asks again once. The first reply then carries one extra line saying so. A session whose version is newer than the running engine's replaces the engine; an older one is told to update. See Messages you may see.

The governor

The engine keeps itself inside a budget. The budget covers the engine and every helper it starts, the checkers and the parse workers included. They all sit in one Windows job object at below normal priority, and they end with the engine.

Limit	Setting	Default
Processor	`engine.cpu_cores`	Half the logical cores, at least 1. Windows holds the engine and its helpers to that share together; this is a hard cap, not a request.
Memory	`engine.memory_mb`	The smaller of 2048 MB and 35 MB for every 100 MB of the computer's memory.

If Windows ever refuses the processor cap, the engine writes "cpu budget: not enforced" to its log (daemon.log, see "Files on your disk") and holds to its budget with lower priority and a cap on parse workers instead.

Questions come first. While any session on any project is waiting for an answer, the engine's background work (making proofs, catching up on saves) pauses, and it carries on afterwards. Parse workers never exceed the processor budget.

When the engine passes its memory budget it gives memory back in this order: it closes the checkers of projects with no session, oldest first; then closes those projects; then restarts a checker that is above its own limit; and last it stops starting new checkers. Answers then say the checker is down, and the labels come from LLMGRAPH's own reading.

What runs, who started it, when it ends

Program	Started by	When it runs	When it ends
Launcher: `node` running `bin/llmgraph.js`	`npx`, for your agent	As long as the session runs	When the session ends. It passes the session's exit code on.
Session: `llmgraph.exe serve`	The launcher	While your agent keeps the connection open	When your agent closes its input, when the launcher is gone (the launcher passes its process id, and the session looks for it every second), or on a stop signal. The shared engine stays for the next session. With `engine.idle_minutes = 0` this program is the whole engine, and it also ends when `stop` asks it to, closing the saved index cleanly so the next start reuses it quickly.
Engine: `llmgraph-engine.exe`	An agent session, when none is running	While a session is attached, then for the idle time	After 20 minutes with no session, or when `stop` asks it to. It shuts down its helpers in order and closes the saved indexes cleanly.
Python checker: `ty.exe`	The engine	When the project has Python files	When the engine shuts down. The engine restarts it if it stops, and gives up after a few restarts.
TypeScript checker: `node.exe` running `ts_bridge.mjs`	The engine, with the same Node that runs the launcher	When the project has TypeScript or JavaScript files	When the engine shuts down.
Parse workers: `llmgraph.exe --parse-worker` (2 to 8)	The engine	Only when many files must be read at once, such as the first read of a big project.	After 60 seconds without a read, or when the engine shuts down.

Which versions, and how to see them

The launcher and the engine package must be the same version. Before it starts anything, the launcher compares the engine package's name and version with its own. If they differ it prints "the installed engine package does not match this launcher" and stops; reinstall the launcher so both come from the same release.

To see what is installed, open the package.json of each package and read its version line. With npx both sit side by side in one folder of npm's cache: node_modules/llmgraph-mcp and node_modules/@brainfoods-studio/win32-x64. The engine also sends its version in the licence check (see what leaves your machine).

Files on your disk

What	Where (Windows)	Notes
Saved indexes, one folder per project	`%LOCALAPPDATA%\llmgraph\stores\<id>`	The id is the first 16 hex digits of a hash of the project's real path. The saved index is encrypted. List them or remove one with `npx -y llmgraph-mcp repos`, which shows each project's folder, when it was last used, and whether an engine has it open.
Project label	`%LOCALAPPDATA%\llmgraph\stores\<id>.label`	Two lines: the project's folder and the time it was last used. It stays on your disk and is never sent. Indexes opened only before 0.4.1 have none until they are opened again; `repos` then says the folder is unknown. Saved indexes are never removed by an update and each counts toward the plan's repositories, so remove the ones you no longer use with `npx -y llmgraph-mcp repos --remove <id>`.
Owner note	`%LOCALAPPDATA%\llmgraph\stores\<id>.owner`	Says which engine has this index open: its process id, when it started, and the launcher's process id. No paths. It is removed when the engine closes the index. If an engine is killed hard, the note stays; `ps` lists it as stale and the next engine takes it over.
Log	`%LOCALAPPDATA%\llmgraph\logs\server.log`	About 1 MB, then it moves to `server.log.1` and starts again. Log lines carry no sign-in token text. The shared engine writes its own `daemon.log` in the same folder, the same way.
Shared engine files	`%LOCALAPPDATA%\llmgraph\engine\`	`daemon.lock` is held while the shared engine runs. `daemon.json` holds its process id, start time, version and pipe name. No project path and no secret.
Checker hash cache	`%LOCALAPPDATA%\llmgraph\tools-hash.json`	Lets the engine skip re-hashing the checker files at each start.
Python checker cache	`%LOCALAPPDATA%\llmgraph\python_lsp\<id>`	One folder per project.
Integrity cache	`%USERPROFILE%\.llmgraph\integrity.cache`	Lets the engine skip re-hashing unchanged install files.
Licence files	`%USERPROFILE%\.llmgraph\licence\`	Your sign-in on this computer.
Usage counts	`%USERPROFILE%\.llmgraph\telemetry\`	`counters\<date>.json` holds the counts for a day; `outbox.json` appears when the day closes (UTC). See what leaves your machine.
Settings file (optional)	`%APPDATA%\llmgraph\config.toml`	Read if it exists. The engine never writes it.
Answer files, in your project	`<project>\.llmgraph\<answer id>.md`	Written when an answer collapsed lines. The folder holds its own `.gitignore` with `*`, so these files never reach a commit.
npm's copy of the packages	`npx` cache; `npm config get cache` shows where	See "A clean install" below.

Environment variables

Set these in the environment of your agent's MCP entry (many agents have an env field for a server). None is needed for a normal install.

Variable	Meaning	Default
`LLMGRAPH_REPO`	The project folder to read. `--repo` wins over it.	Your agent's project folder, else the working folder
`LLMGRAPH_QUERIES`	Which of the five questions to offer, as a comma list. `--queries` wins over it.	All five
`LLMGRAPH_INSTRUCTIONS`	`off` or `describe`. With `describe`, the server adds a short instructions text when your agent connects: how to read an answer, and where to find setup, processes and files (`npx -y llmgraph-mcp help`).	`describe`
`LLMGRAPH_TOOLS_DIR`	A folder with your own checker files, used instead of the bundled ones. Answers are then marked as using unpinned checkers. If the folder does not exist, the checkers do not start; the bundled ones are not used instead.	Not set (bundled checkers)
`LLMGRAPH_GREP_HOOK`	`off` stops the search hint of the Claude Code plugin (see the plugin page). Read by the hint script itself and by the engine's `hook status`.	On
`LLMGRAPH_STOP_HOOK`	`off` stops the stop check of the Claude Code plugin (see the plugin page). Read by the stop-check script itself and by the engine's `hook status`.	On
`LLMGRAPH_NODE`	Set by the launcher to the Node that started it. The engine uses it for the TypeScript checker. Not for users.	Set by the launcher
`LLMGRAPH_LAUNCHER_VERSION`	Set by the launcher to its own version. Not for users.	Set by the launcher
`LLMGRAPH_LAUNCHER_PID`	Set by the launcher to its own process id. The engine ends when that process is gone. Not for users.	Set by the launcher

The engine also reads the Windows locations LOCALAPPDATA, APPDATA and USERPROFILE to find the folders above.

Processes: see them, stop one

List the engines running on this computer:

npx -y llmgraph-mcp ps

Each line has the process id, the project folder, when it started, its age, and whether it is running or stale (the process is gone but its note is still there). It reads only the small owner and label files; it needs no sign-in and no network.

Ask one to stop:

npx -y llmgraph-mcp stop --repo <folder or id>
npx -y llmgraph-mcp stop --all

Without --repo it uses the folder you run it from. stop does not kill anything at first: it asks the engine to shut down through its normal path, then waits up to 10 seconds. Only if the engine is still there does it end that one process, and only when its process id and start time still match the owner note, so it never touches a program that reused the id. It never ends a process tree, and it only acts on our own engines. A stale note is just removed.

If stop reports that a process is still running, use Windows as a last resort. Find the process id with:

tasklist /FI "IMAGENAME eq llmgraph.exe"
tasklist /FI "IMAGENAME eq llmgraph-engine.exe"
tasklist /FI "IMAGENAME eq ty.exe"

and end it, with everything it started, using:

taskkill /F /T /PID <pid>

Two sessions on one project

With the shared engine, two agent sessions on one project simply share it, and nothing below applies to them. Only one engine can have a project's saved index open at a time, so a session gets the message below when a different engine already holds that project's index: an engine from 0.4.1 that is still running, or a session running its own engine because engine.idle_minutes is 0. Its questions then get this message instead of an answer:

llmgraph · another llmgraph (PID <pid>, started <date> UTC) is using the saved index of this project. Ask the user to close the other agent session, or run "npx -y llmgraph-mcp stop".

The part in brackets is left out when the other engine's owner note is not there. Close the other session, or run npx -y llmgraph-mcp ps to see it and stop to end it. The waiting session tries again every 2 seconds, so it recovers by itself once the other engine lets go; nothing was damaged. See Messages you may see.

A clean install

To run the newest release, name it:

npx -y llmgraph-mcp@latest

npx keeps old copies in its cache and may reuse one. To list the cached copies and remove an old one:

npm cache npx ls
npm cache npx rm <key>

Then start your agent again.

Set up with your agentAdd the server, sign in once, check your agent sees it.Messages you may seeEvery fixed message, with what it means.Third-party noticesThe licences of what ships inside the engine package.

For agentsthis page as Markdown/docs/how-it-fits.mdllms.txt