feat(mcp): line numbers in explore output + per-file cluster fixes#188
Merged
Conversation
Follow-up to #185. Three changes to codegraph_explore: 1. Source sections now carry cat -n style line-number prefixes (<num>\t<code>), so the agent can cite file:line straight from the payload instead of re-Reading the file just to recover a line number. Isolated A/B: the no-line-numbers arm spent 2 Reads + a grep to find a line number the line-numbered arm cited with zero follow-up calls. Payload cost ~3-5%. Toggle off with CODEGRAPH_EXPLORE_LINENUMS=0. 2. Per-file cluster selection now ranks clusters containing a query entry point ahead of dense declaration blocks. Density-only ranking buried the relevant methods (perform/didCreateURLRequest/task in Alamofire's Session.swift) under the top-of-file class header + property list. 3. Whole-file "envelope" nodes (a class/struct/etc. spanning >50% of the file) are excluded from clustering. The Session class spans ~1,400 lines; keeping it collapsed every method into one giant cluster that tail-trimmed down to just the class header, hiding the methods. Net vs the 0.7.10 baseline, line numbers on: Alamofire -60%, Excalidraw -32%, VS Code -12% per explore call. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The gap separator and the two tail-trim markers used C-style `//` comments, which aren't comments in Python, Ruby, etc. Switch to plain `... (gap) ...` / `... (trimmed) ...` so they read correctly inside any language's fenced source block. With line numbers on, the line-number jump already corroborates a gap. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sibling to the explore marker fix: codegraph_context's code-block truncation used a C-style `// ... truncated ...`. Switch to `... (truncated) ...` so it reads correctly in any language's fenced source block. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
colbymchenry
added a commit
that referenced
this pull request
May 20, 2026
Folds all changes since 0.7.10 into 0.7.12 (0.7.11 was unpublished from npm): size-adaptive codegraph_explore output budget (#185/#187), line numbers in explore source sections (#188), explore-first tool guidance (#191), language-neutral source-omission markers, and Kotlin/Swift test-file detection (#191). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #185 / #187. Came out of testing the question "what if
codegraph_explorereturned line numbers too?"Changes
Line numbers in explore source sections (
<num>\t<code>, cat -n style, matching the Read tool). Lets the agent citefile:linestraight from the payload instead of re-opening a file just to recover a line number — the dominant residual cost on precise-tracing questions. Toggle off withCODEGRAPH_EXPLORE_LINENUMS=0.Cluster ranking now prioritizes entry points. The I'm missing something? #185 per-file cap ranked clusters purely by density, which buried the relevant methods (
perform/didCreateURLRequest/taskin Alamofire'sSession.swift) under the dense top-of-file class header + property list. Clusters containing a query entry point now rank first; density is a tiebreaker.Whole-file "envelope" nodes excluded from clustering. A
class/struct/etc. spanning >50% of the file (theSessionclass is ~1,400 lines) was collapsing every method into one giant cluster that tail-trimmed down to just the class header. Now dropped from the ranges so the granular methods survive.Fixes 2 and 3 are corrections to the #185 per-file cap (unreleased), surfaced while validating line numbers: the relevant code wasn't making it into the payload, which is why an agent still had to re-read.
Evidence
Isolated A/B (answer "on which exact line is the URLSession task created in
didCreateURLRequest?", relevant code already in payload, two identical Explore subagents):The no-line-numbers arm burned ~4-5k tokens (a Read of lines 1-500) recovering a line number the line-numbered arm cited for the ~130-token payload cost.
Payload size, net vs the 0.7.10 baseline (line numbers on): Alamofire -60%, Excalidraw -32%, VS Code -12% per explore call. (Line numbers add ~3-5%; the cap fixes shifted which lines are shown, not the totals materially.)
Test plan
__tests__/explore-output-budget.test.ts(3 new: line numbers present by default, absent when toggled off, envelope filter keeps method bodies)