# The LLMGRAPH plugin

> One install adds the LLMGRAPH server to your agent, plus a short skill that tells it when to ask which question and how to read the labels.

## 1. Install

For Claude Code, from its plugin marketplace.

In a shell:

```sh
claude plugin marketplace add brainfoods-studio/llmgraph-agent-plugin
claude plugin install llmgraph@llmgraph
```

Or inside a Claude Code session:

```text
/plugin marketplace add brainfoods-studio/llmgraph-agent-plugin
/plugin install llmgraph@llmgraph
```

Other agents: [Set up with your agent](https://beta.llmgraph.in/docs/start.md). More agents follow once each is checked.

## 2. What you get

**The server.** The same five questions as a manual setup. Nothing else changes: you still sign in once.

**The skill.** A short guide your agent loads when a task touches code it is about to change. It says:

- before editing a function, ask `who_calls`;
- before a wider change, ask `what_breaks_if_changed`;
- after editing, ask `check_my_changes`;
- to know where the view ends, ask `what_is_unknown`;
- before relying on a line, ask `explain`;
- treat `maybe_more` and `cannot_see` as open: say so, and don't assume.

## 3. Check it

Ask your agent who calls a function you are about to change. The answer starts with `llmgraph · `. To see the count of calls, run the command below. It prints today's counts on a line that starts `Waiting today (not yet sent)`, then what was already sent or queued. A count sent after the day closes (UTC) moves to the second list; on the day you install, that list reads `(nothing yet)`.

```sh
npx -y llmgraph-mcp telemetry show
```

> The skill makes asking more natural for your agent. It can't make your agent ask every time, so the check above shows you whether it does.

## 4. The search hint

New in plugin version 0.2.0. When your agent in Claude Code searches the code for a function or class name (with or without `def` or `class` in front), the plugin first offers your agent LLMGRAPH's answer as extra context. It asks the LLMGRAPH engine that is already running on your computer whether it knows that name. If it does, your agent gets one short note, for example: the function has 42 callers, 40 of them `certain`, and `who_calls` lists the ones a text search cannot find.

- It never blocks or changes the search. The agent's own search runs as it would have, with its normal permission flow.
- It gives a count only when LLMGRAPH has confirmed that the project's files are unchanged since it last read them. After a save that LLMGRAPH has not yet caught up with, the note carries no number and tells your agent to ask `who_calls` instead.
- It says nothing for file-name searches.
- It stays silent when no engine is running (it never starts one), when the project is not open in the engine, when the name is unknown, when the pattern is not a plain name, and when the engine does not answer within a fraction of a second.
- Your search words go only to your own engine, over a local pipe on your computer. They are not sent over the network, written to a log or counted by name.
- It tells an agent a name once per session in ten minutes.

It is on by default. Switch it off with any one of these:

```sh
npx -y llmgraph-mcp hook off
```

- the setting `grep = "off"` under `[hook]` in your settings file, which `hook off` writes for you (`npx -y llmgraph-mcp hook status` says which is in effect);
- the environment variable `LLMGRAPH_GREP_HOOK=off`;
- removing the plugin, or disabling it in Claude Code.

`npx -y llmgraph-mcp hook on` brings it back.

## 5. The stop check

New in plugin version 0.3.0. When your agent in Claude Code is about to end its turn, the plugin asks the LLMGRAPH engine that is already running on your computer whether your agent's saved edits left calls that are `certain` to break. If they did, the plugin stops your agent from finishing once, and hands it the list: the file and line, the calling function and why the call no longer fits. Your agent then fixes them, or tells you why each is fine. The list is no more than ten lines, for example: `LLMGRAPH: 2 calls break because of your edits:`, then one line per call, then `Fix them, or tell the user why each is fine.`

What blocks:

- Only calls that are `certain` to break, in files that differ from your last commit.

What never blocks:

- Calls LLMGRAPH labels within_these, maybe_more or cannot_see. They are never in the list.
- A second stop in a row. After one block, your agent can finish.
- An engine that is not running (the plugin never starts one), a project that is not open in the engine, an engine that is still reading your files or is busy, an older engine, any error, and any answer that takes longer than a few seconds.

Your folder goes only to your own engine, over a local pipe on your computer. It is not sent over the network or written to a log.

It is on by default. Switch it off with any one of these:

```sh
npx -y llmgraph-mcp hook off
```

- the setting `stop = "off"` under `[hook]` in your settings file, which `hook off` writes for you, together with the search hint (`npx -y llmgraph-mcp hook status` says which is in effect for each);
- the environment variable `LLMGRAPH_STOP_HOOK=off`;
- removing the plugin, or disabling it in Claude Code.

`npx -y llmgraph-mcp hook on` brings both back.

## Read the skill

The skill is plain text, and you can read it before you install.

```text
---
name: llmgraph
description: Use before changing code, after editing, and whenever an LLMGRAPH answer says maybe_more or cannot_see. Explains which of the five LLMGRAPH questions to ask and how to read the labels, reasons and assumptions.
---

# Using LLMGRAPH

LLMGRAPH answers questions about the code in this project, through five MCP tools (the `llmgraph` server). It reads Python and TypeScript/JavaScript files only. An answer says what it can prove, what is within a known set, and what it cannot see. It does not give chances.

## When to ask which question

Before changing a function, method or class:
- `who_calls <symbol>`: the places that call it, with the calls LLMGRAPH cannot see named as such.
- `what_breaks_if_changed <symbol>`: what depends on it, directly or indirectly, and what LLMGRAPH cannot see.

After editing (save the files first; it reads saved files):
- `check_my_changes`: callers you did not update, and anything LLMGRAPH cannot see. Pass `paths` to limit it to the files you edited.
  Pass `tests: true` when you are about to run tests: it lists the tests that call the code you edited.

When an answer says `maybe_more` or `cannot_see`:
- `what_is_unknown`: where the view is blind (dynamic calls, unknown types, unreadable files) and why.
- `explain <handle>`: the evidence behind one answer line. The handle (`w1`, `w2`, ...) comes from an answer in this session and stops working when the server restarts.

## Which tool for which job

Use the cheapest tool that can be right:
- **A plain text search** (grep or your search tool): a name that is unique in the project, a rename that must also change comments, strings and docs, or finding a file. A rename touches text that no code graph lists, so search for it too.
- **Your editor's own go-to-definition, if you have one:** jumping to where one symbol is defined.
- **LLMGRAPH:** a name that also appears in unrelated code (a common method name, two copies of a module), "who calls this" before you change a signature, anything indirect (`what_breaks_if_changed`), "did I miss a caller" after editing (`check_my_changes`), and where the view is blind (`what_is_unknown`). On clean, unique names it saves nothing over a text search; on names that also appear in unrelated code it names the real callers and leaves the look-alikes out.

After an edit, finish with `check_my_changes`: the callers you did not update are the ones a search does not show you.

## How to read an answer

The five labels, strongest first:
- `certain`: provably exactly one function.
- `exactly_these`: a known set, and every member can run here ("all of").
- `within_these`: one of a known list; some listed members may never happen here ("one of").
- `maybe_more`: there are candidates but the door is open (type unknown, a library outside the repository).
- `cannot_see`: nothing to go on (a computed call, a file that could not be read).

Each line below `certain` carries a reason, for example `closed: repo only` or `open: dynamic call`. Treat `open` as "there may be more than listed".

An answer that relies on an assumption says so (`assumes [a]: ...`). Read it before you trust the line it marks.

A `maybe_more` or `cannot_see` line is not a "no". Look at those places yourself, or ask `what_is_unknown`, before you rely on the list. Lines marked as ruled out are ruled out by proof under the assumptions the answer lists (for example "all subclasses are in this repo"), not by guess.

Answers can be listed in full with `expand` on a handle. If an answer says it is not signed in, ask the user to open the link it shows and to approve only if they just started LLMGRAPH on this computer. Do not retry until they confirm.
```