codegraph_explore is token-heavy vs Instant Grep — dumps whole files and can conclude from thin context

[LeDuyViet]

Summary

In real Cursor sessions on a mid-size Go monorepo (~2.3k indexed files), CodeGraph was more token-expensive than a Grep/Read loop for the same architecture question. codegraph_explore returns large verbatim file chunks; agents often call it multiple times and still miss “old vs new” flows, then conclude after only a partial picture.

This is not “CodeGraph is useless” — call-path / blast-radius are valuable — but the default explore surface is too greedy on tokens compared to Instant Grep–style discovery.

Environment

• CodeGraph CLI: 1.5.0 (Windows)
• Agent: Cursor + MCP codegraph serve --mcp
• Project: Go backend, ~2.3k files / ~27k nodes indexed
• Same question run in two fresh chats (same model)

Measured context usage (Cursor “Context Usage”)

Arm	Total context	Conversation slice
CodeGraph-first (codegraph_explore ×4 + 1 Grep)	~60.2K / 256K (24%)	31.8K
Grep/Read only (no CodeGraph)	~40.5K / 256K (16%)	12.0K

Delta ≈ +20K tokens, almost entirely in Conversation (fixed MCP/tool overhead was similar ~4.4K on both).

Self-reported tool counts:

• CodeGraph arm: codegraph_explore=4, Grep=1, Read=0
• Grep arm: Grep=4, Read=7 (targeted slices with offset/limit)

Both arms reached the same correct flow with high confidence. So the extra tokens did not buy a better answer on this task.

Problems observed

1. Explore dumps whole-file (or large multi-file) source

After resolving symbols, codegraph_explore packs verbatim, line-numbered bodies for many files into one response. That is useful for editing, but for “how does X work?” it is often heavier than Instant Grep + a few limited Reads.

Agents are steered to treat explore output as already-Read and not re-verify — which is good — but the payload size still burns the context window hard, especially across multiple explore calls.

2. More expensive than Instant Grep for the same Q&A

For a single structural question (payroll run-all → BuildPayslip → Upsert), Grep/Read used ~half the conversation tokens while producing an equally correct call chain.

CodeGraph’s win on tool-call count / less wandering did not translate to lower tokens when explore returned large sources repeatedly.

3. Hard to tell old vs new flows

In a codebase with CRUD/generated paths next to real workflow UCs, explore sometimes surfaces create/CRUD / DTO layers alongside (or before) the live runPayrollCycleAll path. There is little signal for:

• deprecated / legacy entrypoints vs current workflow
• generated FKIT CRUD vs hand-written UC
• “this route is the one production uses”

So the agent can latch onto a plausible but stale or secondary path unless the human query already names the right symbols.

4. Easy to conclude after a thin pass

Guidance pushes “one explore is often enough.” In practice the first hit can be CRUD-shaped or incomplete (e.g. missing HTTP handler). The agent may still summarize confidently after 1–2 explores + light Grep, while large chunks of returned source are only loosely related — paying tokens for volume without proportional confidence calibration.

What would help (suggestions)

Not prescribing an API — just directions that would fix our pain:

1. Lean explore mode / token budget

   • Summary-first: call graph + file:line + short snippets
   • Opt-in includeSource=full|snippet|none (default snippet for Q&A)
   • Harder maxFiles / per-file line caps that agents actually respect

2. Rank / tag entrypoints

   • Prefer handlers/routes/UCs over DTO/CRUD when the query is “how does X work”
   • Optional tags: generated, test, deprecated (from comments/attrs/path heuristics)

3. Old vs new / primary path

   • Surface “primary call path” vs “also referenced”
   • Or score by inbound refs from HTTP routes / recent git activity

4. Agent instructions

   • Discourage stacking 3–4 explores of the same area
   • Explicitly: if first explore looks like CRUD/DTO only, refine query before answering
   • Remind that Instant Grep + limited Read can be cheaper for narrow symbol lookups

Reproduction (minimal)

1. Index a non-trivial Go service with both generated CRUD and a real workflow UC.
2. In Cursor, ask an architecture question without naming the exact UC (e.g. “how does payroll cycle create and calculate payslips?”).
3. Compare context usage: CodeGraph-first vs Grep/Read-only on the same question in fresh chats.
4. Observe large multi-file source dumps and occasional CRUD-first ranking.

Related expectation

Docs/benchmarks emphasize fewer tool calls and lower tokens vs blind Grep on large repos. Our Cursor measurement on a known, mid-size task showed the opposite for tokens when explore returned full sources multiple times. Happy to share more anonymized traces if useful.