Context
I run Claude Code across 100+ projects and maintain a field-notes repo on configuring it (claude-code-bible — the MCP patterns below are from ch. 7). CodeGraph is attached to several of them, including a 972-file / 10.3k-node / 22k-edge bun monorepo with code spread across apps/*, packages/*, scripts/ — coverage there is excellent (I diffed the index against disk: only dist/ and .vitepress cache excluded, all real source indexed).
Current standing cost per session, measured on v0.9.9: 8 tools ≈ 8.0KB of tools/list schemas + 7.3KB server instructions ≈ ~3.8k tokens in context every request, for every connected agent. #775 shaves the easy ~220 tokens non-breakingly; the ideas below go further but are breaking or design decisions, so they're yours to pick from rather than drive-by PRs.
1. Merge callers / callees / impact into one parameterized tool
All three are the same operation — traverse edges from a symbol — differing only in direction:
codegraph_relations({ symbol, direction: "callers" | "callees" | "impact", depth?, limit? })
8 → 6 tools. Models dispatch on a parameter trivially (it's the same decision as picking among three tools, minus three schemas in context), and the server instructions get one bullet instead of three. The general principle: every per-verb tool pays schema rent every turn; parameters don't.
This also absorbs future tool-count pressure: #728 (codegraph_file_symbols) is already expressible as codegraph_node({ file, symbolsOnly: true }), and #769 (list projects) could be a direction-style mode or a resource (below) instead of a 9th tool.
Migration: keep the old three names as aliases in the execute() switch for a minor version (log a deprecation), and CODEGRAPH_MCP_TOOLS already lets anyone pin the old surface.
2. Implement MCP resources; move read-only diagnostics there
proxy.ts currently answers resources/list with a hardcoded []. Two natural first resources:
codegraph://status — index health. The tool's own description says "Skip unless debugging", yet its schema costs every turn. A resource is exactly the right shape for read-only, rarely-needed diagnostics.codegraph://files/{path} (resource template) — the indexed file tree.
6 → 5 tools (4 with files-as-resource). Caveat: resource support varies across the agents you target (Claude Code reads them on reference; some clients don't surface them) — so keep the tools available behind CODEGRAPH_MCP_TOOLS as a fallback rather than hard-removing them.
3. Document allowlist presets
CODEGRAPH_MCP_TOOLS exists but is undocumented in the README. A documented compact preset (e.g. explore,node,relations — explore is already the do-everything primary) would let context-sensitive users drop to ~3 tools without reading the source. The installer could offer it per agent.
Why bother
The README's pitch is "~16% cheaper · ~58% fewer tool calls" — the tool surface itself is the remaining fixed cost. Every KB of always-on schema competes with the user's actual code context, multiplied across all 8 supported agents.
Happy to PR any subset of these if you want them — #775 is the non-breaking first step.
🤖 Generated with Claude Code
Context
I run Claude Code across 100+ projects and maintain a field-notes repo on configuring it (claude-code-bible — the MCP patterns below are from ch. 7). CodeGraph is attached to several of them, including a 972-file / 10.3k-node / 22k-edge bun monorepo with code spread across
apps/*,packages/*,scripts/— coverage there is excellent (I diffed the index against disk: onlydist/and.vitepresscache excluded, all real source indexed).Current standing cost per session, measured on v0.9.9: 8 tools ≈ 8.0KB of
tools/listschemas + 7.3KB server instructions ≈ ~3.8k tokens in context every request, for every connected agent. #775 shaves the easy ~220 tokens non-breakingly; the ideas below go further but are breaking or design decisions, so they're yours to pick from rather than drive-by PRs.1. Merge
callers/callees/impactinto one parameterized toolAll three are the same operation — traverse edges from a symbol — differing only in direction:
8 → 6 tools. Models dispatch on a parameter trivially (it's the same decision as picking among three tools, minus three schemas in context), and the server instructions get one bullet instead of three. The general principle: every per-verb tool pays schema rent every turn; parameters don't.
This also absorbs future tool-count pressure: #728 (
codegraph_file_symbols) is already expressible ascodegraph_node({ file, symbolsOnly: true }), and #769 (list projects) could be adirection-style mode or a resource (below) instead of a 9th tool.Migration: keep the old three names as aliases in the
execute()switch for a minor version (log a deprecation), andCODEGRAPH_MCP_TOOLSalready lets anyone pin the old surface.2. Implement MCP resources; move read-only diagnostics there
proxy.tscurrently answersresources/listwith a hardcoded[]. Two natural first resources:codegraph://status— index health. The tool's own description says "Skip unless debugging", yet its schema costs every turn. A resource is exactly the right shape for read-only, rarely-needed diagnostics.codegraph://files/{path}(resource template) — the indexed file tree.6 → 5 tools (4 with files-as-resource). Caveat: resource support varies across the agents you target (Claude Code reads them on reference; some clients don't surface them) — so keep the tools available behind
CODEGRAPH_MCP_TOOLSas a fallback rather than hard-removing them.3. Document allowlist presets
CODEGRAPH_MCP_TOOLSexists but is undocumented in the README. A documentedcompactpreset (e.g.explore,node,relations— explore is already the do-everything primary) would let context-sensitive users drop to ~3 tools without reading the source. The installer could offer it per agent.Why bother
The README's pitch is "~16% cheaper · ~58% fewer tool calls" — the tool surface itself is the remaining fixed cost. Every KB of always-on schema competes with the user's actual code context, multiplied across all 8 supported agents.
Happy to PR any subset of these if you want them — #775 is the non-breaking first step.
🤖 Generated with Claude Code