github/codegraph
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(mcp): adaptive codegraph_explore sizing — skeletonize redundant polymorphic siblings (#564)

Browse Source 
codegraph_explore now skeletonizes off-spine, redundant members of a polymorphic
family (OkHttp's interceptor chain, Django's SQLCompiler family) to signatures
instead of shipping every full body, while keeping the dispatch mechanism, the
orchestrator/base, and any method the agent named in full. Sizes the response to
the answer rather than the budget cap, so interface-heavy flows stop costing more
than plain grep/read. Default on; CODEGRAPH_ADAPTIVE_EXPLORE=0 disables.

Gate: off-spine + >=3-impl sibling + not-spared, where spared = the agent named a
callable in the file UNLESS the file defines the family's supertype (a huge
base+subclasses file is Read-anyway, so skeletonizing frees explore budget).

Validated headless A/B (Opus 4.8): both former README cost outliers flipped —
OkHttp and Django went from costlier-than-native to cheaper; full 7-repo average
22%% cheaper / 47%% fewer tokens / 20%% faster / 50%% fewer tool calls, every repo
cost-positive, inert repos unchanged. 7-case regression test.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Colby Mchenry
2026-05-29 14:42:00 -05:00
committed by GitHub
co-authored by Claude Opus 4.8
parent f58de8a391
commit f1b14f021b
5 changed files with 819 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+52 -52
View File
@@ -4,7 +4,7 @@
### Supercharge Claude Code, Cursor, Codex, OpenCode, Hermes Agent, Gemini, Antigravity, and Kiro with Semantic Code Intelligence
**~18% cheaper · ~57% fewer tool calls · 100% local**
**~22% cheaper · ~50% fewer tool calls · 100% local**
### [Documentation & Website →](https://colbymchenry.github.io/codegraph/)
@@ -83,21 +83,21 @@ When Claude Code explores a codebase, it spawns **Explore agents** that scan fil
### Benchmark Results
Tested across **7 real-world open-source codebases** spanning 7 languages, comparing an agent (Claude Code, headless) answering one architecture question **with** and **without** CodeGraph. Each cell is the savings at the **median of 4 runs per arm**. _Re-validated on **v0.9.7** + Opus 4.8 (2026-05-28)._
Tested across **7 real-world open-source codebases** spanning 7 languages, comparing an agent (Claude Code, headless) answering one architecture question **with** and **without** CodeGraph. Each cell is the savings at the **median of 4 runs per arm**. _Re-validated on Opus 4.8 (2026-05-29), on the build with adaptive `codegraph_explore` sizing._
> **Average: 18% cheaper · 51% fewer tokens · 16% faster · 57% fewer tool calls**
> **Average: 22% cheaper · 47% fewer tokens · 20% faster · 50% fewer tool calls**
| Codebase | Language | Cost | Tokens | Time | Tool calls |
|----------|----------|------|--------|------|------------|
| **VS Code** | TypeScript · ~10k files | 26% cheaper | 63% fewer | 20% faster | 69% fewer |
| **Excalidraw** | TypeScript · ~640 | 40% cheaper | 71% fewer | 41% faster | 82% fewer |
| **Django** | Python · ~3k | 10% costlier | 45% fewer | 3% slower | 64% fewer |
| **Tokio** | Rust · ~790 | 30% cheaper | 69% fewer | 22% faster | 71% fewer |
| **OkHttp** | Java · ~645 | 3% costlier | 32% fewer | 15% faster | 60% fewer |
| **Gin** | Go · ~110 | 7% cheaper | 35% fewer | 8% faster | 38% fewer |
| **Alamofire** | Swift · ~110 | 38% cheaper | 45% fewer | 6% faster | 8% fewer |
| **VS Code** | TypeScript · ~10k files | 13% cheaper | 63% fewer | 11% faster | 82% fewer |
| **Excalidraw** | TypeScript · ~640 | 40% cheaper | 71% fewer | 51% faster | 82% fewer |
| **Django** | Python · ~3k | 9% cheaper | 35% fewer | 7% faster | 38% fewer |
| **Tokio** | Rust · ~790 | 31% cheaper | 59% fewer | 29% faster | 61% fewer |
| **OkHttp** | Java · ~645 | 4% cheaper | 16% fewer | 11% faster | 40% fewer |
| **Gin** | Go · ~110 | 28% cheaper | 40% fewer | 25% faster | 35% fewer |
| **Alamofire** | Swift · ~110 | 32% cheaper | 43% fewer | 6% faster | 13% fewer |
CodeGraph cuts **tool calls and total tokens on every repo** and answers large repos with **zero file reads**, while the no-CodeGraph agent spends its budget on grep/find/Read discovery. The **cost** margin is narrower — and occasionally negative on smaller repos (Django, OkHttp) — because a modern model's native search is already cheap and CodeGraph's richer responses cost real input tokens; the consistent wins are fewer tool calls and faster answers.
CodeGraph cuts **tool calls and total tokens on every repo** and answers large repos with **zero file reads**, while the no-CodeGraph agent spends its budget on grep/find/Read discovery. **Every repo is now cheaper, not just faster** — the two former cost outliers (Django and OkHttp, where the answer spans many interchangeable implementations of one interface) flipped from *costlier* than native search to cheaper once adaptive `codegraph_explore` sizing stopped shipping every sibling's full body. The margin is still narrowest on the smallest repos, where a modern model's native search is already cheap, but it stays positive across the board; the largest wins remain fewer tool calls and faster answers.
<details>
<summary><strong>Per-repo breakdown — WITH vs WITHOUT (median of 4)</strong></summary>
@@ -105,79 +105,79 @@ CodeGraph cuts **tool calls and total tokens on every repo** and answers large r
**VS Code** · ~10k files
| Metric | WITH cg | WITHOUT cg | Δ |
|---|---|---|---|
| Time | 1m 49s | 2m 16s | 20% faster |
| File Reads | 0 | 7 | −7 |
| Time | 1m 58s | 2m 13s | 11% faster |
| File Reads | 0 | 8 | −8 |
| Grep/Bash | 0 | 9 | −9 |
| Tool calls | 5 | 16 | 71% fewer |
| Total tokens | 672k | 1.81M | 63% fewer |
| Cost | $0.66 | $0.89 | 26% cheaper |
| Tool calls | 3 | 17 | 82% fewer |
| Total tokens | 607k | 1.65M | 63% fewer |
| Cost | $0.66 | $0.76 | 13% cheaper |
**Excalidraw** · ~640 files
| Metric | WITH cg | WITHOUT cg | Δ |
|---|---|---|---|
| Time | 1m 41s | 2m 51s | 41% faster |
| Time | 1m 23s | 2m 48s | 51% faster |
| File Reads | 0 | 11 | −11 |
| Grep/Bash | 0 | 11 | −11 |
| Tool calls | 4 | 22 | 82% fewer |
| Total tokens | 692k | 2.39M | 71% fewer |
| Cost | $0.63 | $1.04 | 40% cheaper |
| Grep/Bash | 0 | 9 | −9 |
| Tool calls | 4 | 20 | 82% fewer |
| Total tokens | 596k | 2.06M | 71% fewer |
| Cost | $0.53 | $0.89 | 40% cheaper |
**Django** · ~3k files
| Metric | WITH cg | WITHOUT cg | Δ |
|---|---|---|---|
| Time | 2m 2s | 1m 58s | 4% slower |
| File Reads | 2 | 10 | −8 |
| Grep/Bash | 0 | 5 | −5 |
| Tool calls | 5 | 14 | 64% fewer |
| Total tokens | 720k | 1.30M | 45% fewer |
| Cost | $0.70 | $0.64 | 10% costlier |
| Time | 1m 43s | 1m 51s | 7% faster |
| File Reads | 5 | 10 | −5 |
| Grep/Bash | 0 | 4 | −4 |
| Tool calls | 8 | 13 | 38% fewer |
| Total tokens | 752k | 1.16M | 35% fewer |
| Cost | $0.56 | $0.62 | 9% cheaper |
**Tokio** · ~790 files
| Metric | WITH cg | WITHOUT cg | Δ |
|---|---|---|---|
| Time | 1m 54s | 2m 26s | 22% faster |
| File Reads | 0 | 11 | −11 |
| Grep/Bash | 0 | 6 | −6 |
| Tool calls | 5 | 17 | 73% fewer |
| Total tokens | 657k | 2.10M | 69% fewer |
| Cost | $0.61 | $0.86 | 30% cheaper |
| Time | 2m 3s | 2m 53s | 29% faster |
| File Reads | 3 | 9 | −6 |
| Grep/Bash | 0 | 7 | −7 |
| Tool calls | 7 | 17 | 61% fewer |
| Total tokens | 869k | 2.14M | 59% fewer |
| Cost | $0.63 | $0.92 | 31% cheaper |
**OkHttp** · ~645 files
| Metric | WITH cg | WITHOUT cg | Δ |
|---|---|---|---|
| Time | 1m 18s | 1m 32s | 15% faster |
| File Reads | 1 | 5 | −4 |
| Grep/Bash | 0 | 6 | −6 |
| Tool calls | 4 | 10 | 58% fewer |
| Total tokens | 713k | 1.05M | 32% fewer |
| Cost | $0.59 | $0.57 | 3% costlier |
| Time | 1m 18s | 1m 27s | 11% faster |
| File Reads | 2 | 4 | −2 |
| Grep/Bash | 0 | 4 | −4 |
| Tool calls | 5 | 8 | 40% fewer |
| Total tokens | 739k | 883k | 16% fewer |
| Cost | $0.54 | $0.56 | 4% cheaper |
**Gin** · ~110 files
| Metric | WITH cg | WITHOUT cg | Δ |
|---|---|---|---|
| Time | 1m 12s | 1m 18s | 9% faster |
| File Reads | 0 | 4 | −4 |
| Grep/Bash | 0 | 4 | −4 |
| Tool calls | 5 | 8 | 40% fewer |
| Total tokens | 533k | 815k | 35% fewer |
| Cost | $0.44 | $0.47 | 7% cheaper |
| Time | 1m 8s | 1m 30s | 25% faster |
| File Reads | 0 | 3 | −3 |
| Grep/Bash | 0 | 5 | −5 |
| Tool calls | 6 | 9 | 35% fewer |
| Total tokens | 532k | 887k | 40% fewer |
| Cost | $0.36 | $0.50 | 28% cheaper |
**Alamofire** · ~110 files
| Metric | WITH cg | WITHOUT cg | Δ |
|---|---|---|---|
| Time | 2m 0s | 2m 7s | 6% faster |
| File Reads | 6 | 8 | −2 |
| Grep/Bash | 2 | 4 | −2 |
| Tool calls | 11 | 12 | 9% fewer |
| Total tokens | 1.09M | 1.98M | 45% fewer |
| Cost | $0.63 | $1.01 | 38% cheaper |
| Time | 2m 19s | 2m 28s | 6% faster |
| File Reads | 5 | 9 | −4 |
| Grep/Bash | 1 | 4 | −3 |
| Tool calls | 11 | 12 | 13% fewer |
| Total tokens | 1.22M | 2.14M | 43% fewer |
| Cost | $0.71 | $1.04 | 32% cheaper |
</details>
<details>
<summary><strong>Full benchmark details</strong></summary>
**Methodology.** Each arm is `claude -p` (Claude Opus 4.8) run headlessly against the repo with `--strict-mcp-config`: **WITH** = CodeGraph's MCP server enabled, **WITHOUT** = an empty MCP config. Built-in Read/Grep/Bash stay available to both. Same question per repo, **4 runs per arm, median reported**. Cost = the run's `total_cost_usd`; Tokens = total tokens processed (input incl. cached + output); Time = wall-clock; Tool calls = every tool invocation, including those inside any sub-agents the model spawns. Repos cloned at `--depth 1` and indexed by the same CodeGraph build that served them. Re-validated on codegraph **v0.9.7** (2026-05-28). These numbers are lower than the prior Opus 4.7 validation — not a CodeGraph regression but a stronger native baseline: Opus 4.8 greps/reads efficiently on the main thread instead of fanning out into large Explore-subagent sweeps, so the no-CodeGraph arm is leaner than it used to be. Per-repo numbers move run-to-run with how hard the without-arm thrashes (the median-of-4 smooths it, but tails remain — e.g. Django's without-arm hit $2.71/14m one batch).
**Methodology.** Each arm is `claude -p` (Claude Opus 4.8) run headlessly against the repo with `--strict-mcp-config`: **WITH** = CodeGraph's MCP server enabled, **WITHOUT** = an empty MCP config. Built-in Read/Grep/Bash stay available to both. Same question per repo, **4 runs per arm, median reported**. Cost = the run's `total_cost_usd`; Tokens = total tokens processed (input incl. cached + output); Time = wall-clock; Tool calls = every tool invocation, including those inside any sub-agents the model spawns. Repos cloned at `--depth 1` and indexed by the same CodeGraph build that served them. Re-validated 2026-05-29 on the build with adaptive `codegraph_explore` sizing. These numbers are lower than the prior Opus 4.7 validation — not a CodeGraph regression but a stronger native baseline: Opus 4.8 greps/reads efficiently on the main thread instead of fanning out into large Explore-subagent sweeps, so the no-CodeGraph arm is leaner than it used to be. Per-repo numbers move run-to-run with how hard the without-arm thrashes (the median-of-4 smooths it, but tails remain — e.g. Django's without-arm hit $2.71/14m one batch).
**Queries:**
| Codebase | Query |