Every time I watched an AI coding assistant work on a large TypeScript project, I noticed the same pattern.
It wanted to answer something simple like:
- "Where is this hook defined?"
- "Who calls this function?"
- "What's the type of this value?"
Instead of reading a single symbol, it often opened an entire file.
Sometimes that meant loading 50 KB... sometimes 100 KB... just to extract a 30-line function.
Multiply that by dozens of requests during a coding session, and you quickly end up wasting thousands of tokens on code the model never actually needed.
So I built SymbolPeek.
What it does
SymbolPeek is an MCP server that gives AI coding agents symbol-level access to a codebase.
Instead of asking for a whole file, an agent can ask for exactly what it needs:
- read a single function
- find all references
- navigate to definitions
- inspect callers and callees
- resolve inferred TypeScript types
- inspect call hierarchies
- read only the surrounding context of a symbol
The result is dramatically smaller context with much richer information than plain text search.
Example
Imagine a file with nearly 1,800 lines.
Instead of this:
Open the entire file.
the model can simply ask:
read_symbol(
path: ".../worker.js",
symbol: "createProject.collectImports"
)
and receive only the function it requested.
In one real example from the project itself, the response was about 2 KB instead of reading a 65 KB source file.
The model gets exactly what it asked for—and nothing else.
Real usage
I wanted to know whether semantic navigation actually reduces context consumption for LLMs.
So I added lifetime statistics.
After normal day-to-day development, these are my current numbers:
Requests: 162
Files avoided: 163
Lines avoided: 352,910
Bytes avoided: 6.4 MB
Estimated tokens saved: ~1.61M
Average context reduction: 95.7%
These aren't synthetic benchmarks.
They're collected during real development while working with AI coding agents.
Each request compares the semantic response against the counterfactual of reading the complete source files involved.
The result surprised me more than I expected.
More than 95% of the source context simply wasn't necessary.
Why not just use grep?
Text search is fantastic.
I still use grep every day.
But grep doesn't understand:
- import aliases
- barrel exports
- inferred generic types
- call graphs
- definitions
- semantic references
The TypeScript compiler already knows all of this.
Instead of parsing text again, SymbolPeek simply exposes the compiler's knowledge through MCP.
Multi-language support
The project started as a TypeScript tool because that's where semantic navigation provides the biggest payoff.
Today it supports:
- TypeScript
- JavaScript
- Rust
- Python
- Java
- Go
- JSON
- Markdown
TypeScript and JavaScript use the official TypeScript Compiler API for semantic analysis.
Rust, Python, Java, Go, JSON and Markdown currently use Tree-sitter for fast syntax-aware navigation.
That means the same MCP server can be useful across mixed-language repositories instead of only TypeScript projects.
What makes it different?
One thing I wanted to avoid was building "grep over MCP."
If a language already has a production-grade compiler capable of answering semantic questions, why ignore it?
For TypeScript, SymbolPeek uses the compiler itself to provide:
- compiler-resolved references
- module resolution
- path aliases
- barrel re-exports
- inferred generic types
- diagnostics
- call hierarchy
The information already exists.
The MCP server simply exposes it to AI coding agents.
Current capabilities
For TypeScript and JavaScript:
- symbol navigation
- references
- callers
- callees
- definitions
- diagnostics
- call hierarchy
- type inspection
- document outline
Other supported languages currently provide syntax-aware navigation through Tree-sitter.
The goal
The goal isn't to replace grep.
It isn't to replace reading source files.
It's to eliminate one of the most expensive workflows AI agents perform every day:
Open a huge file just to inspect one declaration.
Less context.
Fewer tokens.
Better signal.
I'd love feedback
I'm especially interested in hearing from people building AI coding tools or working with:
- Codex
- Claude Code
- Cursor
- Cline
- Roo Code
- Windsurf
- other MCP-enabled agents
Have you ever watched an AI spend thousands of tokens reading files just to answer a simple navigation question?
I'd love to hear how you're solving that today.
GitHub:
Top comments (2)
I really like the direction here. Treating the compiler as the source of truth instead of asking an LLM to rediscover semantic information from raw text feels like the right abstraction.
One thing I’d be careful about is generalizing the 95% reduction. It makes perfect sense for navigation tasks (definitions, references, call hierarchy), but architecture-level reasoning often benefits from broader context than a single symbol.
One idea that could be interesting is making the MCP server context-aware over time. Instead of returning only symbols, it could expose a semantic dependency graph and support incremental queries based on what the agent already knows. At that point, you’re no longer optimizing file reads—you’re optimizing knowledge acquisition.
Yeah, the 95% is fair to poke at. It's just the average over the requests I've actually run, and those are almost all navigation stuff — "where's this defined", "who calls this", that kind of thing. So of course it comes out high. It was never meant as "every task shrinks 95%." When I'm actually trying to understand how a chunk of the system fits together I still read the whole file or grep around like normal. The tool isn't trying to win that case. It's just trying to not dump a 2k-line file when all the agent wanted was one function.
The graph thing is interesting because part of it already sort of exists-
But you're pointing at the harder part it doesn't do: it's completely stateless. Every call starts from zero and it has no clue what the agent already pulled, so it'll happily hand back the same subtree it gave you two calls ago.
Making it remember that within a session and only return the delta is honestly not how I'd been thinking about it, and it's a better framing than "save file reads." No idea when I'd get to it, but it's going to be stuck in my head now