feat: Update Claude instructions to discourage direct codegraph tool usage in main session

colbymchenry · colbymchenry · commit 4d65d60dedae · 2026-04-03T17:03:03.000-05:00
Changes guidance to recommend spawning Explore agents for exploration questions instead of using codegraph_explore/codegraph_context directly in main session to avoid filling up context with large amounts of source code. Adds completeness signal to codegraph_explore output so agents know not to re-read files that already have source code included.
diff --git a/src/installer/claude-md-template.ts b/src/installer/claude-md-template.ts
@@ -16,21 +16,25 @@ CodeGraph builds a semantic knowledge graph of codebases for faster, smarter cod
 
 ### If \`.codegraph/\` exists in the project
 
-**Use codegraph tools directly in the main session.** Codegraph replaces the need for Explore agents in most cases. Instead of spawning an agent (which takes 30+ tool calls and 1+ minutes), use codegraph MCP tools directly for fast, structured answers:
+**NEVER call \`codegraph_explore\` or \`codegraph_context\` directly in the main session.** These tools return large amounts of source code that fills up main session context. Instead, ALWAYS spawn an Explore agent for any exploration question (e.g., "how does X work?", "explain the Y system", "where is Z implemented?").
 
-| Tool | Use For |
-|------|---------|
-| \`codegraph_explore\` | **Deep exploration** — comprehensive context for a topic in ONE call (replaces Explore agents) |
-| \`codegraph_context\` | Quick context for a task (lighter than explore) |
-| \`codegraph_search\` | Find symbols by name (functions, classes, types) |
-| \`codegraph_callers\` | Find what calls a function |
-| \`codegraph_callees\` | Find what a function calls |
-| \`codegraph_impact\` | See what's affected by changing a symbol |
-| \`codegraph_node\` | Get details + source code for a symbol |
+**When spawning Explore agents**, include this instruction in the prompt:
+
+> This project has CodeGraph initialized (.codegraph/ exists). Use \`codegraph_explore\` as your PRIMARY tool — it returns full source code sections from all relevant files in one call.
+>
+> **Rules:**
+> 1. Make at most 3 \`codegraph_explore\` calls — one broad query, then up to 2 focused follow-ups.
+> 2. Do NOT re-read files that codegraph_explore already returned source code for. The source sections are complete and authoritative.
+> 3. Only fall back to grep/glob/read for files listed under "Additional relevant files" if you need more detail, or if codegraph returned no results.
 
-**For deep exploration questions** (e.g., "how does the undo/redo system work?"), use \`codegraph_explore\` directly. It returns full source code sections from all relevant files in a single call — no need to spawn an Explore agent.
+**The main session may only use these lightweight tools directly** (for targeted lookups before making edits, not for exploration):
 
-**Do NOT tell Explore agents to use codegraph tools.** Testing shows Explore agents use codegraph for discovery then still read all the same files — making them slower, not faster. Codegraph's value is in the main session where it replaces the need for exhaustive file reading.
+| Tool | Use For |
+|------|---------|
+| \`codegraph_search\` | Find symbols by name |
+| \`codegraph_callers\` / \`codegraph_callees\` | Trace call flow |
+| \`codegraph_impact\` | Check what's affected before editing |
+| \`codegraph_node\` | Get a single symbol's details |
 
 ### If \`.codegraph/\` does NOT exist
 
diff --git a/src/mcp/tools.ts b/src/mcp/tools.ts
@@ -849,6 +849,11 @@ export class ToolHandler {
       }
     }
 
+    // Add completeness signal so agents know they don't need to re-read these files
+    lines.push('');
+    lines.push('---');
+    lines.push(`> **Complete source code is included above for ${filesIncluded} files.** You do NOT need to re-read these files — the relevant sections are already shown in full. Only use Read/Grep for files listed under "Additional relevant files" if you need more detail.`);
+
     return this.textResult(lines.join('\n'));
   }
 

Original file line number	Diff line number	Diff line change
`@@ -849,6 +849,11 @@ export class ToolHandler {`
`849`	`849`	`}`
`850`	`850`	`}`
`851`	`851`
	`852`	`+ // Add completeness signal so agents know they don't need to re-read these files`
	`853`	`+ lines.push('');`
	`854`	`+ lines.push('---');`
	`855`	+ lines.push(`> Complete source code is included above for ${filesIncluded} files. You do NOT need to re-read these files — the relevant sections are already shown in full. Only use Read/Grep for files listed under "Additional relevant files" if you need more detail.`);
	`856`	`+`
`852`	`857`	`return this.textResult(lines.join('\n'));`
`853`	`858`	`}`
`854`	`859`