b48170e69f
Two coupled changes addressing the issue's underlying ask — "how does the
agent know when the index lags" — without resorting to a static wait.
Per-file staleness banner
-------------------------
FileWatcher now tracks per-path `pendingFiles` (path, firstSeenMs,
lastSeenMs, indexing) — events since the last successful sync, cleared
only after a sync whose `syncStartedMs >= lastSeenMs` commits. Chokidar
initial-scan events are gated behind a `ready` flag (with `waitUntilReady()`
exposed so tests can deterministically wait through it) so a fresh startup
doesn't falsely flag every existing file as pending.
ToolHandler now wraps every code-returning response (search, context,
callers, callees, impact, trace, explore, node, files) with
`withStalenessNotice`: intersects "files referenced in the response" with
`getPendingFiles()` and emits a hybrid signal —
* banner at the top for files referenced AND pending (with edit age +
indexing/pending-sync state, telling the agent to Read those specific
files directly; the rest of the response stays fresh and codegraph
stays authoritative for it),
* compact footer for pending files elsewhere in the project not
referenced above (capped at 5).
Cost is one boolean check + N substring matches when pending; zero
allocation when idle. `codegraph_status` surfaces the same data as a
first-class `### Pending sync:` section so the agent can ask "is the index
caught up?" in one call.
Cross-project quirk: when an agent passes `projectPath` matching the
default session's project, the staleness wrapper switches from the cached
cross-project CodeGraph (no watcher) to the default one (with watcher) so
the signal still fires. Same fix applied to `handleStatus`.
CODEGRAPH_WATCH_DEBOUNCE_MS
---------------------------
MCP `serve --mcp` now reads `CODEGRAPH_WATCH_DEBOUNCE_MS` and forwards it
to `cg.watch({ debounceMs })`. Clamped to [100ms, 60s]; out-of-range or
non-numeric values fall back to the FileWatcher default (2000ms). Active
value is logged to stderr on watcher startup so it's discoverable. The
docs in `server-instructions.ts`, `installer/instructions-template.ts`,
and `.cursor/rules/codegraph.mdc` no longer claim "~500ms"; they now
describe the banner mechanism instead — since per-file staleness replaces
the "wait N ms" guidance entirely, the docs become accurate at any
debounce value.
Validation
----------
* 847 unit/integration tests pass (added 15 new ones — pending-file
tracking, banner/footer routing, status section, env-var parsing).
* Direct MCP probe through a real `codegraph serve --mcp` process: edit a
file, query within the debounce window, banner fires naming the
edited file with edit-age.
* Real Claude TUI session via `scripts/agent-eval/itrun.sh` with
`CODEGRAPH_WATCH_DEBOUNCE_MS=10000`: agent edits `math.ts`, calls
`codegraph_explore`, reads the banner, **and discloses it unprompted in
its final reply**: "note: symbol index is mid-sync for the new `divide`,
but the source it returned is verbatim from disk."
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
65 lines
4.4 KiB
TypeScript
65 lines
4.4 KiB
TypeScript
/**
|
|
* Agent-instructions template — the markdown body each agent target
|
|
* writes into its conventional instructions file (CLAUDE.md /
|
|
* AGENTS.md / codegraph.mdc / etc.).
|
|
*
|
|
* The body content is identical across agents because the codegraph
|
|
* usage advice is agent-agnostic — only the destination filename and
|
|
* any optional frontmatter (Cursor `.mdc`) varies per target.
|
|
*
|
|
* The legacy `claude-md-template.ts` re-exports these names for
|
|
* backwards compatibility with downstream importers.
|
|
*/
|
|
|
|
/** Markers used by the marker-based section replacement. */
|
|
export const CODEGRAPH_SECTION_START = '<!-- CODEGRAPH_START -->';
|
|
export const CODEGRAPH_SECTION_END = '<!-- CODEGRAPH_END -->';
|
|
|
|
/**
|
|
* The full marker-delimited block written into each agent's
|
|
* instructions file. Includes the start/end markers so the section
|
|
* can be detected and replaced on re-install.
|
|
*/
|
|
export const INSTRUCTIONS_TEMPLATE = `${CODEGRAPH_SECTION_START}
|
|
## CodeGraph
|
|
|
|
This project has a CodeGraph MCP server (\`codegraph_*\` tools) configured. CodeGraph is a tree-sitter-parsed knowledge graph of every symbol, edge, and file. Reads are sub-millisecond and return structural information grep cannot.
|
|
|
|
### When to prefer codegraph over native search
|
|
|
|
Use codegraph for **structural** questions — what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open.
|
|
|
|
| Question | Tool |
|
|
|---|---|
|
|
| "Where is X defined?" / "Find symbol named X" | \`codegraph_search\` |
|
|
| "What calls function Y?" | \`codegraph_callers\` |
|
|
| "What does Y call?" | \`codegraph_callees\` |
|
|
| "How does X reach/become Y? / trace the flow from X to Y" | \`codegraph_trace\` (one call = the whole path, incl. callback/React/JSX dynamic hops) |
|
|
| "What would break if I changed Z?" | \`codegraph_impact\` |
|
|
| "Show me Y's signature / source / docstring" | \`codegraph_node\` |
|
|
| "Give me focused context for a task/area" | \`codegraph_context\` |
|
|
| "See several related symbols' source at once" | \`codegraph_explore\` |
|
|
| "What files exist under path/" | \`codegraph_files\` |
|
|
| "Is the index healthy?" | \`codegraph_status\` |
|
|
|
|
### Rules of thumb
|
|
|
|
- **Answer directly — don't delegate exploration.** For "how does X work" / architecture questions, answer with 2-3 codegraph calls: \`codegraph_context\` first, then ONE \`codegraph_explore\` for the source of the symbols it surfaces. For a specific **flow** ("how does X reach Y") start with \`codegraph_trace\` from→to — one call returns the whole path with dynamic hops bridged — then ONE \`codegraph_explore\` for the bodies; don't rebuild the path with \`codegraph_search\` + \`codegraph_callers\`. Codegraph IS the pre-built index, so spawning a separate file-reading sub-task/agent — or running a grep + read loop — repeats work codegraph already did and costs more for the same answer.
|
|
- **Trust codegraph results.** They come from a full AST parse. Do NOT re-verify them with grep — that's slower, less accurate, and wastes context.
|
|
- **Don't grep first** when looking up a symbol by name. \`codegraph_search\` is faster and returns kind + location + signature in one call.
|
|
- **Don't chain \`codegraph_search\` + \`codegraph_node\`** when you just want context — \`codegraph_context\` is one call.
|
|
- **Don't loop \`codegraph_node\` over many symbols** — one \`codegraph_explore\` call returns several symbols' source grouped in a single capped call, while each separate node/Read call re-reads the whole context and costs far more.
|
|
- **Index lag — check the staleness banner, don't guess a wait.** When a codegraph response starts with "⚠️ Some files referenced below were edited since the last index sync…", the listed files are pending re-index — Read those specific files for accurate content. Files NOT in that banner are fresh and codegraph is authoritative for them. \`codegraph_status\` also lists pending files under "Pending sync".
|
|
|
|
### If \`.codegraph/\` doesn't exist
|
|
|
|
The MCP server returns "not initialized." Ask the user: *"I notice this project doesn't have CodeGraph initialized. Want me to run \`codegraph init -i\` to build the index?"*
|
|
${CODEGRAPH_SECTION_END}`;
|
|
|
|
/**
|
|
* Backwards-compat alias. Existing downstream code may import
|
|
* `CLAUDE_MD_TEMPLATE` from this module via the re-export shim in
|
|
* `claude-md-template.ts`.
|
|
*/
|
|
export const CLAUDE_MD_TEMPLATE = INSTRUCTIONS_TEMPLATE;
|