feat(cli+installer): codegraph explore/node CLI + instructions-file block — subagent & non-MCP reach (#704) (#819)
Task-tool subagents never see the MCP initialize instructions and hold the MCP tools only as deferred names they rarely think to load — so delegated work bypassed codegraph almost entirely (measured ~1 of 9 forced-delegation runs touched it; the rest did 30-50 grep/read calls). Two additions close the gap: - CLI: `codegraph explore` and `codegraph node` call the same ToolHandler as the MCP tools and print identical output — the graph for any agent with a shell (subagents, Gemini CLI, raw Codex, humans). - Installer: each agent target (claude/codex/gemini/opencode) writes a short marker-fenced CodeGraph section into its instructions file — the one channel subagents DO receive — naming both surfaces. Upsert self-heals the stale pre-#529 long block; uninstall strips it; re-runs are byte-equal unchanged. (#529's duplication argument bounded the size: four lines, commands only.) A/B (excalidraw, sonnet/high, forced Explore-agent delegation): without the block, subagent codegraph usage ~1/9 runs; with it, 4/4 — subagents ToolSearch-load the MCP tools and run explore 5-7x, best runs with ZERO Read/grep (80-95s vs 150-197s baseline). The block's mechanism: the parent relays the note into the task prompt, making the deferred tool names salient. Contract tests updated to the new expectations (write + self-heal replace the #529 strip-only behavior); README install/guidance sections refreshed (they also still described the pre-#817/#818 tool surface). Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Colby Mchenry
co-authored by
Claude Opus 4.8
Claude Opus 4.8
parent
c450fd95b7
commit
8170d181f2
@@ -1,18 +1,40 @@
|
||||
/**
|
||||
* Marker constants for the legacy agent-instructions block.
|
||||
* The marker-fenced agent-instructions block the installer writes into each
|
||||
* agent's instructions file (CLAUDE.md / AGENTS.md / GEMINI.md).
|
||||
*
|
||||
* Codegraph used to write a `## CodeGraph` usage guide into each
|
||||
* agent's instructions file (CLAUDE.md / AGENTS.md / GEMINI.md /
|
||||
* codegraph.mdc / Kiro steering doc). That duplicated the guidance the
|
||||
* MCP server already emits in its `initialize` response — every agent
|
||||
* read the same playbook twice each turn (issue #529). The installer no
|
||||
* longer writes an instructions file; the MCP server instructions in
|
||||
* `mcp/server-instructions.ts` are the single source of truth.
|
||||
* History: pre-#529 the installer wrote a full usage playbook here, which
|
||||
* duplicated the MCP `initialize` instructions for the main agent — so it
|
||||
* was removed and `mcp/server-instructions.ts` became the single source of
|
||||
* truth. A much smaller block returned for #704, because the MCP
|
||||
* instructions cannot reach two audiences that the instructions FILE does
|
||||
* reach:
|
||||
*
|
||||
* These markers are retained so install (self-heal on upgrade) and
|
||||
* uninstall can find and strip the block a previous install wrote.
|
||||
* - **Task-tool subagents** — they receive the project instructions file
|
||||
* in their context but NOT the MCP initialize instructions. They hold
|
||||
* the codegraph MCP tools only as deferred names and rarely think to
|
||||
* load them: measured on a forced-delegation flow question (excalidraw,
|
||||
* sonnet, high effort), subagents loaded + used codegraph in ~1 of 9
|
||||
* runs without this block, and consistently with it — including runs
|
||||
* with zero Read/grep fallback.
|
||||
* - **Non-MCP harnesses** — agents with no MCP client at all can still
|
||||
* run the `codegraph explore` / `codegraph node` CLI, which prints the
|
||||
* same output as the MCP tools.
|
||||
*
|
||||
* Keep this block SHORT. The main agent reads it every turn on top of the
|
||||
* server instructions — the #529 duplication-cost argument still bounds
|
||||
* its size. Command names and the two surfaces, nothing more.
|
||||
*/
|
||||
|
||||
/** Markers used by the marker-based section removal. */
|
||||
/** Markers used by the marker-based section write/removal. */
|
||||
export const CODEGRAPH_SECTION_START = '<!-- CODEGRAPH_START -->';
|
||||
export const CODEGRAPH_SECTION_END = '<!-- CODEGRAPH_END -->';
|
||||
|
||||
/** The full block, markers included, exactly as written to disk. */
|
||||
export const CODEGRAPH_INSTRUCTIONS_BLOCK = `${CODEGRAPH_SECTION_START}
|
||||
## CodeGraph
|
||||
|
||||
This repository is indexed by CodeGraph — a pre-built code knowledge graph. Reach for it BEFORE grep/find or reading files when you need to understand or locate code:
|
||||
|
||||
- **MCP tools** (when available): \`codegraph_explore\` answers most code questions in one call — the relevant symbols' verbatim source plus the call paths between them. \`codegraph_node\` returns one symbol's source + callers, or reads a whole file with line numbers. If the tools are listed but deferred, load them by name via tool search.
|
||||
- **Shell** (always works): \`codegraph explore "<symbol names or question>"\` and \`codegraph node <symbol-or-file>\` print the same output.
|
||||
${CODEGRAPH_SECTION_END}`;
|
||||
|
||||
@@ -34,6 +34,7 @@ import {
|
||||
readJsonFile,
|
||||
removeMarkedSection,
|
||||
writeJsonFile,
|
||||
upsertInstructionsEntry,
|
||||
} from './shared';
|
||||
import {
|
||||
CODEGRAPH_SECTION_END,
|
||||
@@ -120,15 +121,12 @@ class ClaudeCodeTarget implements AgentTarget {
|
||||
const hookCleanup = cleanupLegacyHooks(loc);
|
||||
if (hookCleanup.action === 'removed') files.push(hookCleanup);
|
||||
|
||||
// 3. CLAUDE.md instructions — no longer written. The codegraph
|
||||
// usage guidance now ships solely in the MCP server's `initialize`
|
||||
// response (see `mcp/server-instructions.ts`), which Claude Code
|
||||
// surfaces in the system prompt automatically. Writing it into
|
||||
// CLAUDE.md as well meant the agent read the same playbook twice
|
||||
// every turn (issue #529). Strip any block a previous install left
|
||||
// behind so an upgrade self-heals — same idiom as the hook cleanup.
|
||||
const instrCleanup = removeInstructionsEntry(loc);
|
||||
if (instrCleanup.action === 'removed') files.push(instrCleanup);
|
||||
// 3. CLAUDE.md instructions — the short marker-fenced CodeGraph
|
||||
// block (#704). The MCP initialize instructions reach only the main
|
||||
// agent; CLAUDE.md is what Task-tool subagents (and non-MCP
|
||||
// harnesses) actually see, so the block carries the codegraph
|
||||
// pointers there. Upsert self-heals a stale pre-#529 long block.
|
||||
files.push(upsertInstructionsEntry(instructionsPath(loc)));
|
||||
|
||||
return { files };
|
||||
}
|
||||
|
||||
@@ -28,6 +28,7 @@ import {
|
||||
atomicWriteFileSync,
|
||||
getMcpServerConfig,
|
||||
removeMarkedSection,
|
||||
upsertInstructionsEntry,
|
||||
} from './shared';
|
||||
import {
|
||||
CODEGRAPH_SECTION_END,
|
||||
@@ -83,11 +84,10 @@ class CodexTarget implements AgentTarget {
|
||||
|
||||
files.push(writeMcpEntry());
|
||||
|
||||
// AGENTS.md is no longer written — the codegraph usage guidance
|
||||
// ships in the MCP server's `initialize` response (issue #529).
|
||||
// Strip a block a previous install left so an upgrade self-heals.
|
||||
const instrCleanup = removeInstructionsEntry();
|
||||
if (instrCleanup.action === 'removed') files.push(instrCleanup);
|
||||
// AGENTS.md gets the short marker-fenced CodeGraph block (#704):
|
||||
// subagents and non-MCP harnesses read AGENTS.md but never the MCP
|
||||
// initialize instructions. Upsert self-heals a stale pre-#529 block.
|
||||
files.push(upsertInstructionsEntry(instructionsPath()));
|
||||
|
||||
return { files };
|
||||
}
|
||||
|
||||
@@ -38,6 +38,7 @@ import {
|
||||
readJsonFile,
|
||||
removeMarkedSection,
|
||||
writeJsonFile,
|
||||
upsertInstructionsEntry,
|
||||
} from './shared';
|
||||
import {
|
||||
CODEGRAPH_SECTION_END,
|
||||
@@ -84,11 +85,10 @@ class GeminiTarget implements AgentTarget {
|
||||
const files: WriteResult['files'] = [];
|
||||
files.push(writeMcpEntry(loc));
|
||||
|
||||
// GEMINI.md is no longer written — the codegraph usage guidance
|
||||
// ships in the MCP server's `initialize` response (issue #529).
|
||||
// Strip a block a previous install left so an upgrade self-heals.
|
||||
const instrCleanup = removeInstructionsEntry(loc);
|
||||
if (instrCleanup.action === 'removed') files.push(instrCleanup);
|
||||
// GEMINI.md gets the short marker-fenced CodeGraph block (#704):
|
||||
// subagents and non-MCP harnesses read GEMINI.md but never the MCP
|
||||
// initialize instructions. Upsert self-heals a stale pre-#529 block.
|
||||
files.push(upsertInstructionsEntry(instructionsPath(loc)));
|
||||
|
||||
return { files };
|
||||
}
|
||||
|
||||
@@ -41,6 +41,7 @@ import {
|
||||
atomicWriteFileSync,
|
||||
jsonDeepEqual,
|
||||
removeMarkedSection,
|
||||
upsertInstructionsEntry,
|
||||
} from './shared';
|
||||
import {
|
||||
CODEGRAPH_SECTION_END,
|
||||
@@ -127,11 +128,10 @@ class OpencodeTarget implements AgentTarget {
|
||||
const files: WriteResult['files'] = [];
|
||||
files.push(writeMcpEntry(loc));
|
||||
|
||||
// AGENTS.md is no longer written — the codegraph usage guidance
|
||||
// ships in the MCP server's `initialize` response (issue #529).
|
||||
// Strip a block a previous install left so an upgrade self-heals.
|
||||
const instrCleanup = removeInstructionsEntry(loc);
|
||||
if (instrCleanup.action === 'removed') files.push(instrCleanup);
|
||||
// AGENTS.md gets the short marker-fenced CodeGraph block (#704):
|
||||
// subagents and non-MCP harnesses read AGENTS.md but never the MCP
|
||||
// initialize instructions. Upsert self-heals a stale pre-#529 block.
|
||||
files.push(upsertInstructionsEntry(instructionsPath(loc)));
|
||||
|
||||
return { files };
|
||||
}
|
||||
|
||||
@@ -10,6 +10,11 @@
|
||||
|
||||
import * as fs from 'fs';
|
||||
import * as path from 'path';
|
||||
import {
|
||||
CODEGRAPH_INSTRUCTIONS_BLOCK,
|
||||
CODEGRAPH_SECTION_START,
|
||||
CODEGRAPH_SECTION_END,
|
||||
} from '../instructions-template';
|
||||
|
||||
/**
|
||||
* The MCP-server config block codegraph injects. Same shape across
|
||||
@@ -167,6 +172,26 @@ export function replaceOrAppendMarkedSection(
|
||||
return 'appended';
|
||||
}
|
||||
|
||||
/**
|
||||
* Upsert the CodeGraph instructions block into an agent instructions
|
||||
* file (CLAUDE.md / AGENTS.md / GEMINI.md). The one write shared by
|
||||
* every target: self-heals a stale pre-#529 long block (markers match →
|
||||
* replaced by the current short one), appends after existing user
|
||||
* content otherwise, and reports `unchanged` on byte-equal re-runs so
|
||||
* install stays idempotent. See `instructions-template.ts` for why this
|
||||
* block exists (#704: subagents + non-MCP harnesses never see the MCP
|
||||
* initialize instructions).
|
||||
*/
|
||||
export function upsertInstructionsEntry(file: string): { path: string; action: 'created' | 'updated' | 'unchanged' } {
|
||||
const action = replaceOrAppendMarkedSection(
|
||||
file,
|
||||
CODEGRAPH_INSTRUCTIONS_BLOCK,
|
||||
CODEGRAPH_SECTION_START,
|
||||
CODEGRAPH_SECTION_END,
|
||||
);
|
||||
return { path: file, action: action === 'appended' ? 'updated' : action };
|
||||
}
|
||||
|
||||
/**
|
||||
* Inverse of `replaceOrAppendMarkedSection`. Strips the marker
|
||||
* block from `filePath` if present. If the file becomes empty after
|
||||
|
||||
Reference in New Issue
Block a user