feat(mcp): size-adaptive output budget for codegraph_explore (#185)#187
Merged
Conversation
Output is now scaled to indexed file count. Small projects (<500 files) cap at ~18KB and skip the "Additional relevant files" / completeness / explore-budget reminders that earn their keep on larger codebases; medium (<5,000) caps at ~28KB; large (<15,000) keeps the historical ~35KB; very large goes up to ~38KB. A per-file char cap also prevents a single file with many adjacent symbols from collapsing into one whole-file dump (the pathological Alamofire `Session.swift` case reported in #185), and a per-file symbol- list cap stops the `#### path — sym(kind), ...` header from leaking multi-KB lists when many adjacent symbols cluster together. Measured against the README's benchmark repos: Alamofire (~100 files) ~62% smaller per call, Excalidraw (~600 files) ~35%, VS Code (~10k files) ~14%. Agent-trust floor preserved — Relationships, scored cluster selection, and structured-source output are all retained. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closed
3 tasks
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.
Summary
codegraph_exploreoutput with a size-adaptive budget keyed off indexed file count (closes I'm missing something? #185).Session.swiftcollapsed into one whole-file dump.Why
#185 reported
codegraph_exploreusing ~2x the tokens of native grep+Read on a ~100-file Next.js project. The README's own Alamofire benchmark (102 files) shows the same pattern. Root cause: the fixed 35KB cap is sized for thousands-of-files codebases where the agent's discovery cost (grep + find + many Reads) earns the rich output; on small projects it's a tax.Measured impact
Against the same repos used in the README benchmark, average over 3 representative queries each:
Agent-trust floor preserved: an Explore subagent on Alamofire still answered the full
Session.request()→ URLSession trace from the new lean output, using 1 explore call + 3 Reads for line-level detail (normal pattern for cross-file tracing, not a fallback to native discovery).Tier breakpoints
Matches the existing
getExploreBudgetso a project sits in the same tier across both knobs:Test plan
__tests__/explore-output-budget.test.tscovering tier breakpoints, off-by-one boundaries, and end-to-end budget enforcement against a synthetic small project