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.

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

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

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 · 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 · 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 · 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 · 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 · 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 · 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 · 2026-05-26 · closed · 0 comments

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

Describe the bug

src/symbols.ts:128:

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

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 · 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 · 2026-05-26 · closed · 0 comments

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

Problem

Even with sharper MCP tool descriptions (#9), some clients route best when given a per-repo rules file:

Read the thread · 2026-05-26 · closed · 0 comments

The remaining reports are on the project's issue tracker.