# Reported issues for GraphPilot

Pod holds 16 of 17 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [GraphPilot](/mcp/graphpilot).

## Most discussed

### [P2] gp_index from agent silently mutates external watcher state

## Describe the bug

`src/mcp.ts:handleGpIndex` calls `indexDirectory`, writes `graph.json`, and `invalidateCache(root)`. But a separately-running `graphpilot watch` process has its own in-memory `this.graph` that is not notified — and on the next file event the watcher will overwrite the fresh re-index. (Same root cause as P0-5.)

## Reproduction

Steps to reproduce:

1. Terminal A: `graphpilot watch ./repo`.
2. Terminal B: start an MCP client (Cursor) pointed at `./repo`; have the agent call `

[Read the thread](https://github.com/graphpilot-oss/graphpilot/issues/33) · 2026-05-26 · closed · 1 comment

### [P2][dx] Split gp_callers into gp_callers + gp_callees for better agent tool discovery

## Describe the bug

`src/mcp.ts:TOOLS` exposes `gp_callers` as one tool with a `direction: 'callers' | 'callees'` enum. Agents discovering tools via `tools/list` see only the name and description — they have to read the description to learn `direction` is even an option, and to learn that `'callees'` is the other half.

Agents tend to pick tools by name + description matching the user's intent. `gp_callees` would show up as a distinct callable when reasoning about "what does X depend on?"; `gp_

[Read the thread](https://github.com/graphpilot-oss/graphpilot/issues/32) · 2026-05-26 · open · 1 comment

### bug: [P0][4] No cross-process locking on graph.json — concurrent writers corrupt the index

Every writer (CLI `index`, `gp_index` MCP tool, `graphpilot watch`) does:

```ts
writeFileSync(tmpPath, ...);
renameSync(tmpPath, path);
```

That's atomic for a **single** writer. With two writers — e.g. Cursor + Claude Code both running an MCP server against the same repo, or `graphpilot watch` running alongside an agent calling `gp_index` — last-write-wins silently discards the other's work.

Additionally, `indexCache` in `src/mcp.ts:34` caches a `GraphIndex` per process and **never invalidat

[Read the thread](https://github.com/graphpilot-oss/graphpilot/issues/15) · 2026-05-26 · closed · 1 comment

### feat: [P2][resolver] Follow re-export chains to the true source

## Problem
Re-export chains like `index.ts → utils/index.ts → utils/string.ts` resolve to whichever file the walker saw first, not the true definition source.

## Proposal
Follow `export { x } from './y'` / `export * from './y'` chains to the originating symbol. Builds on import-path resolution (#TBD).

## Acceptance
- [ ] A 2+ hop re-export resolves to the true source symbol
- [ ] Cyclic re-exports terminate safely (no infinite loop) — test included
- [ ] Measured precision on `bench/resolver/`

[Read the thread](https://github.com/graphpilot-oss/graphpilot/issues/74) · 2026-06-13 · open · 0 comments

### chore: [P1] connect-failure triage lane — template checkbox + P0 policy

## Problem
Connect/startup failures are the highest-severity report class for an MCP server — they make the tool look broken on first contact. We need them to route to a fast lane automatically.

## Proposal
- `connect-failure` label exists — wire it into the bug issue template as a checkbox ("the agent can't connect to / start the server").
- Template should request `graphpilot doctor --json` output (#TBD).
- Document the triage policy in `docs/agents/triage-labels.md`: `connect-failure` ⇒ P0, 

[Read the thread](https://github.com/graphpilot-oss/graphpilot/issues/71) · 2026-06-13 · closed · 0 comments

### fix: [P1] Stat failure can silently serve a stale cached graph (mcp.ts cache check)

## Problem
In `src/mcp.ts` the cache-validation check (around lines 86–93) treats `currentMtimeMs === 0` as a cache-bypass condition:

```ts
const cached = indexCache.get(root);
if (
  cached &&
  currentMtimeMs !== 0 &&
  cached.mtimeMs === currentMtimeMs &&
  cached.sizeBytes === currentSizeBytes
```

`currentMtimeMs === 0` is the sentinel for a failed `stat`. The intent is "if we can't stat, don't trust the cache" — but a `stat` failure *after* the cache is warm currently falls through to ser

[Read the thread](https://github.com/graphpilot-oss/graphpilot/issues/69) · 2026-06-13 · closed · 0 comments

### test: [P1] Enforce MCP cold-start under a 500ms budget

## Problem
Agent clients silently kill MCP servers that are slow to answer `initialize`. A regression that pushes cold start over the client's tolerance shows up to users as "the tools disappeared," with no error.

## Proposal
Add a regression test asserting the MCP server reaches "ready to serve" (responds to `initialize` + `tools/list`) within a budget — target **< 500 ms cold** — driven in-process (no `child_process`).

## Acceptance
- [ ] Test fails if cold start exceeds the budget
- [ ] Bud

[Read the thread](https://github.com/graphpilot-oss/graphpilot/issues/68) · 2026-06-13 · closed · 0 comments

### feat: [P1] Return a structured "no index found" error instead of empty results

## Problem
When `graph.json` is missing or fails schema validation, MCP tool calls currently return empty results. From the agent's side, "no index exists" is indistinguishable from "this symbol genuinely has no callers" — so the agent reports a confident wrong answer instead of telling the user to index.

## Proposal
On the first tool call against a missing/corrupt graph, return a **structured, agent-readable error** rather than an empty result set, e.g. `no index found for <root> — run \`graph

[Read the thread](https://github.com/graphpilot-oss/graphpilot/issues/67) · 2026-06-13 · closed · 0 comments

## Most recent

### feat: [P1][dx] `graphpilot init` auto-registers the MCP server in detected client configs

## Problem
Install today is: `npm i -g`, then hand-edit the MCP config for your client at a client-specific path. The hand-edit step is where "agent can't see the tools" begins. `graphpilot init` already detects installed editors and writes routing rules — it should also be able to register the MCP server entry.

## Proposal
Add `graphpilot init --register` (name TBD) that inserts the `mcpServers.graphpilot` entry into each detected client config.

- Confirmation prompt before writing; honor `--

[Read the thread](https://github.com/graphpilot-oss/graphpilot/issues/66) · 2026-06-13 · closed · 0 comments

### feat: [P1] `graphpilot doctor` — health/diagnostic command for connect failures

## Problem
When an agent client (Claude Code, Cursor, Cline, Windsurf, Continue) can't see the `gp_*` tools, the user has no fast way to find out *why* — is Node missing, is the bin off PATH, is the graph absent, is the MCP config wrong, did the handshake hang? Today that's a manual scavenger hunt.

## Proposal
Add a `graphpilot doctor` command that runs an ordered checklist and prints `✓/✗` with one actionable fix line per failure.

Checks:
- [ ] Node ≥ 20 present + version reported
- [ ] globa

[Read the thread](https://github.com/graphpilot-oss/graphpilot/issues/65) · 2026-06-13 · closed · 0 comments

### [P2][security] loadGraph doesn't verify the loaded graph matches the requested root path

## Describe the bug

`src/storage.ts:loadGraph` loads whatever's at `graphPath(absRoot)` and runs schema validation — but doesn't verify the file's `rootPath` / `repoId` matches what the caller asked for.

`~/.graphpilot` is user-writable and `repoId` is a short hash prefix, so a copied or restored `graph.json` from another repo will be served if it lands in the matching directory.

## Reproduction

Steps to reproduce:

1. `graphpilot index ~/proj-A` — note `repoId-A` printed.
2. `graphpilot ind

[Read the thread](https://github.com/graphpilot-oss/graphpilot/issues/29) · 2026-05-26 · closed · 0 comments

### bug: [P1] interactions.jsonl grows unbounded — no rotation, no size cap

## Describe the bug

`src/interactions.ts:logInteraction` is append-only. There is no rotation, no size cap, and no age-based reaper. On a busy MCP install (one entry per tool call, every Cursor/Claude Code session) the log grows ~5–10 KB per minute. Over weeks this becomes a multi-GB file in `~/.graphpilot/<repo>/`.

The log is intentionally kept for future personalized ranking (per the in-code comment, "Day-1 logs become day-180 personalized ranking"), but unbounded growth makes that an active

[Read the thread](https://github.com/graphpilot-oss/graphpilot/issues/24) · 2026-05-26 · closed · 0 comments

### bug: [P1] Symbol IDs embed @<line>, so any edit invalidates every downstream reference

## Describe the bug

`src/symbols.ts:128`:

```ts
const id = `${parsed.path}#${parent ? parent + '.' : ''}${name}@${line}`;
```

Adding a single blank line at the top of a file changes the `@line` suffix in every symbol id below, so all ids in that file are effectively rotated on every edit. The `interactions.jsonl` log becomes un-anchorable, watcher consumers see id churn, and the evidence-anchor pitch (the marquee differentiator) points at moving targets.

## Reproduction

Steps to reproduce:

[Read the thread](https://github.com/graphpilot-oss/graphpilot/issues/20) · 2026-05-26 · open · 0 comments

### bug: [P1] Ambiguous symbol resolution is silent — agent can't tell when toId is a guess

## Describe the bug

`src/edges.ts:resolveCallEdges` picks the first matching symbol when multiple exist, with no signal that disambiguation was needed:

```ts
const sameFile = candidates.find((s) => s.file === c.file);
if (sameFile) return { ...c, toId: sameFile.id };
return { ...c, toId: candidates[0].id };
```

The agent sees a populated `toId`, treats it as authoritative, and acts on it. `limitations.md` documents the name-only resolver, but the failure mode is **invisible** to downstream co

[Read the thread](https://github.com/graphpilot-oss/graphpilot/issues/18) · 2026-05-26 · closed · 0 comments

### bug: [P1] JSX elements are invisible to the call graph — React/TSX users get zero callers

## Describe the bug

`src/edges.ts:extractRawCalls` only emits call edges for `call_expression` and `new_expression` AST nodes. JSX component usages (`<Foo />`, `<Foo>...</Foo>`) are `jsx_self_closing_element` / `jsx_opening_element` nodes, so React/Solid/Preact component references are silently absent from the call graph.

This is the most common structural question on TSX projects ("who renders `Header`?"), and `gp_callers Header` looks like it works but returns nothing.

## Reproduction

Step

[Read the thread](https://github.com/graphpilot-oss/graphpilot/issues/17) · 2026-05-26 · closed · 0 comments

### Add `graphpilot init` command — auto-drop per-client routing rules

## Problem

Even with [sharper MCP tool descriptions (#9)](https://github.com/graphpilot-oss/graphpilot/issues/9), some clients route best when given a per-repo rules file:

| Client | Rules file | Mechanism |
|---|---|---|
| Cursor | `.cursorrules` (repo root) | Cursor auto-loads on every session |
| Windsurf | `.windsurfrules` (repo root) | Cascade auto-loads |
| Cline | `.clinerules` (repo root) | Cline auto-loads |
| Continue.dev | `.continuerules` (repo root) | Continue auto-loads |
| Claud

[Read the thread](https://github.com/graphpilot-oss/graphpilot/issues/10) · 2026-05-26 · closed · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/graphpilot-oss/graphpilot/issues).