/ Recomputation → Reuse · AI Execution Layer v… / mit license

# Make AI agents understand your codebase — not just read it.

A structured map of your codebase for AI agents. trace-mcp indexes your repo once and serves it through MCP — so agents query a precomputed graph instead of re-reading the same files on every turn.

- ~40–50% fewer tokens on average
- Faster responses as the codebase grows
- More reliable results at scale

Analyze your AI system → View on GitHub `npx trace-mcp benchmark .` copy

Open source MIT licensed Used in real LLM workflows Runs locally · no data leaves your machine

~40–50% Average token reduction across mixed agent workloads
up to 99% In structured workflows — repeated navigation, dependency traversal, context re-inflation
up to 2× Effective context capacity per session

Measured against baseline agent runs that re-read files and re-traverse dependencies on every turn. Run `npx trace-mcp benchmark .` to reproduce on your own repo.

Y Built by a Y Combinator alum MIT License Open source · MIT … npm downloads last month … GitHub stars … watching
/ Built For Modern AI Coding Stacks
MCP Claude Code Cursor Windsurf Claude Desktop VS Code
trace-mcp / graph explorer symbols · edges · live
Languages
0
tree-sitter + lsp
Integrations
0
15 fw / 7 orm / 13 ui / 23 other
MCP Tools
0
read-only or audited
Avg Token Reduction
40–50%
on real agent workflows
001 / Problem

## AI agents recompute work they've already done.

Every turn, the agent re-reads the same files, re-traverses the same dependencies, and re-inflates the context window with structure it discovered five steps ago. Token bills grow. Latency grows. Reasoning quality drops. The model isn't the bottleneck — the recomputation leak is.

01 The same files get read 5–15 times in a single task as the agent traverses dependencies blind.
02 Context window is treated like a database — bloated with structure that's already been computed.
03 Framework edges are invisible: routes ↔ controllers ↔ models ↔ views are rediscovered each turn.
04 Cost, latency, and hallucinations all grow with project size instead of with task complexity.

Agents recompute instead of reusing.

002 / Solution

## Trace. Diagnose. Optimize. Control.

Four layers that move AI systems from recomputation to reuse. We start at the noisiest place agents work today — the codebase — and turn what they keep re-reading into a structure they query once.

Show the leak. Explain it. Close it. Keep it closed.

01 Trace — surface what your agent actually reads, re-reads, and re-traverses. Repeated reads, fan-out, context growth, recomputation hotspots — visible per task.
02 Diagnose — explain why work is being recomputed: blind dependency traversal, missing framework edges, context bloat after step N, recursion past depth K.
03 Optimize — replace recomputation with a precomputed, framework-aware graph served via MCP. One `get_change_impact` call instead of 80 Greps and 190 reads.
04 Control — keep reuse the default: incremental reindex, repeated-read detection, agent-behavior rules, optimization policies that survive every session.
003 / Product View

## A structured model of your codebase that agents can use.

An AI agent reading `UserController.php` sees a class. trace-mcp sees the route that hits it, the form request that validates input, the model it touches, the page it renders, the components rendered inside.

### This is how agents stop recomputing and start reusing.

Computed once — every symbol, every edge, across 81 languages in one directed graph. The agent queries it instead of rediscovering it each turn.

Framework-aware — routes to controllers, Inertia to Vue, Eloquent to migrations. 58 integrations capture edges the agent would otherwise reconstruct from raw files.

Compiler-grade where it matters — optional LSP enrichment with `tsserver`, `pyright`, `gopls` for call resolution that survives across calls.

Reused, not rebuilt — 300ms file-watcher debounce and content-hashed incremental reindex keep the graph fresh without redoing finished work.

/ Cross-Language Edge Trace
PHP routes/web.php
↓ routes_to
PHP UserController@show
↓ validates_with
PHP UserShowRequest
↓ queries
SQL users · posts
↓ renders_via_inertia
VUE Pages/Users/Show.vue
↓ uses_component
VUE UserCard, PostList
004 / How It Works

## Three steps. Setup in minutes.

Connect. Index. Expose. After that, agents operate with full context — and the graph stays in sync automatically as you code.

01

#### Connect your repository

Run `trace-mcp add` in your repo. Frameworks are detected automatically — Laravel, Django, Next.js, NestJS, Rails, 58 in total.

cli auto-detect no api keys
02

#### Index into a graph

Tree-sitter parses symbols, plugins resolve framework edges, optional LSP enriches with compiler-grade call data. Stored locally in SQLite + FTS5.

tree-sitter 138 mcp tools local sqlite
03

#### Expose to your agents

138 MCP tools become available in Claude Code, Cursor, Windsurf, VS Code — or any custom agent that speaks MCP over stdio or HTTP.

mcp stdio + http read-only default

Recomputation becomes reuse.

005 / Core Capabilities

## The five calls that replace 90% of recomputation.

Five tools from a surface of 138 — the ones agents reach for first. Each one collapses what would otherwise be a chain of Reads, Greps, and Globs into a single graph query. Token cost drops; the answer gets sharper.

search Structure-aware search across your codebase — by symbol kind, FQN, interface, or intent. Ranks by Signal Fusion (BM25 + PageRank + embeddings + identity). graph + fts5
get_outline Understand file and module structure instantly. Signatures only — cheaper than reading the file. ~200 tok avg
find_usages Track where functions, classes, and variables are used. Semantic edges, not grep — imports, calls, renders, dispatches. edge index
get_call_graph Analyze execution paths across the system, bidirectional. LSP-enriched where available, with confidence tiers. bidirectional
apply_codemod Safely modify code with awareness of dependencies. Dry-run preview, diff review, reversible. dry-run default

+ 133 more — impact analysis, decision memory, security, architecture. Full reference →

006 / Positioning

## Traditional tools make agents recompute harder.

Sourcegraph, Glean, Cursor's indexer — powerful, but optimized for humans reading code one screen at a time. Pointed at an agent loop, they return more text to re-process, not less work to do.

/ Human-first tools

#### Search results for the agent to re-read

- Returns files and snippets — the agent still has to traverse them
- Same query, same output, every turn — no reuse across calls
- No unified graph; framework edges are rediscovered from text
- Bolted onto agent workflows, not designed for them

/ Agent-native trace-mcp

#### A precomputed graph the agent reuses

- 138 tools that return answers, not files to read
- One incremental index, queried per task — not rebuilt per turn
- Single graph across every symbol, edge, and framework
- Native MCP protocol, zero adapter code

Agents need reuse, not more search.

007 / Differentiation

## Reuse is the unlock, not more search.

- / 01 Computed once, queried many times — a graph, not a text index that gets re-ranked every turn.
- / 02 Framework-aware edges across 58 integrations — routes, ORMs, views, DI captured up front, not rediscovered from raw files.
- / 03 Tools that return answers, not snippets to read — `get_change_impact`, `get_call_graph`, `find_usages` over a precomputed structure.
- / 04 Reuse survives the session — incremental reindex, decision memory, agent-behavior rules keep cost from rebounding.

This is not code search.
This is recomputation → reuse for AI systems.

008 / Desktop App

## Or skip the CLI. See the graph directly.

An optional desktop companion bundles the MCP server with a GPU-accelerated graph explorer. Inspect projects, watch incremental indexing in real time, browse the exact structure your AI agents see.

overview index · coverage · services
projects multi-repo · mcp clients
009 / Benchmark

## Token cost, measured — not marketed.

Structured benchmarks on a real codebase (856 files, 4,774 symbols), native Read/Grep/Glob vs trace-mcp tools, via `benchmark_project`. These are peak structured-task numbers, not average production. On mixed real-world workloads expect ~40–50%; on non-code tasks, 0%. The peaks are where the math gets dramatic.

Type hierarchy
195,717 → 1,030 tokens tree-walk vs read-all
99.5%
Symbol lookup
44,265 → 1,023 tokens indexed search vs grep
97.7%
Composite task
82,291 → 2,929 tokens 1 call vs ~10 sequential
96.4%
Impact analysis
119,441 → 5,976 tokens graph traversal vs guess
95.0%
Call graph
115,570 → 6,937 tokens bidirectional
94.0%
Find usages
11,430 → 1,720 tokens edge index vs grep
85.0%
Peak structured-task reduction across 11 categories on the trace-mcp TS/Vue codebase — the recomputation that gets eliminated when the agent reuses a precomputed graph instead of re-reading files. Real production sessions mix structured calls with reads and edits, so net reduction lands at ~40–50% on mixed workloads. Less noise also means fewer hallucinations and stronger first-response accuracy.
up to 97%
010 / Use Cases

## Where trace-mcp belongs in your stack.

/ 01 · AI Coding Agents Navigate large repos. Make correct changes.

Graph traversal instead of file-by-file reading. Agents ship features with fewer broken changes and less context thrash.

get_task_context · get_change_impact
/ 02 · Developer Platforms Smarter copilots and assistants.

Plug trace-mcp into internal dev tools. Your copilot answers "what calls this?" in one call instead of ten.

find_usages · get_outline
/ 03 · Engineering Teams Reduce risk in automated changes.

Every codemod previewed, every rename graph-verified. PR bots comment with symbol-level diff and blast radius.

apply_codemod · compare_branches
011 / Security

## Built for real-world environments.

Runs fully local. No code leaves your machine. Refactors are reversible. Destructive operations require explicit confirmation.

Local-first

#### Repository-level access control

One SQLite database per project under `~/.trace-mcp/`. Nothing is written inside your repo unless you opt in.

Zero egress

#### Secure handling of code

No API keys, no cloud services. Bundled ONNX embeddings. Fully offline after first install.

Audited writes

#### Safe modification workflows

Every refactor has a dry-run preview and diff review. Guard hook blocks destructive operations from agents.

012 / Ecosystem

## 58 integrations. 81 languages.

Each integration adds framework-specific edges — routes, components, migrations, queries — not just syntax parsing. Plugin API is open: write your own for a niche framework in under a day.

Laravel
Django
FastAPI
NestJS
Next.js
Spring
Rails
Express
Flask
Fastify
Hono
Nuxt
Gin
Echo
Filament
React
Vue
Angular
Svelte
Blade
Inertia
shadcn/ui
MUI
Ant Design
Headless UI
Tailwind
React Native
Prisma
TypeORM
Drizzle
SQLAlchemy
Sequelize
Mongoose
Eloquent
GraphQL
tRPC
DRF
MCP SDK
Socket.io
Pydantic
Zod
Zustand
Celery
Electron
n8n
Vitest
Jest
pytest
Playwright
013 / Install

## See your waste first. Then wire it in.

Run one command and watch the recomputation surface. No config, no API keys, no signup — embeddings ship with the binary, everything stays local.

01

#### / See Your Waste

npx trace-mcp benchmark .

Indexes the project, runs 11 structured task benchmarks, prints per-task token cost — without trace-mcp vs. with. Time-to-value: ~5 minutes on a real repo.

02

#### / Wire In Your Agent

npx trace-mcp init

Configures your MCP client (Claude Code, Cursor, Windsurf), installs the guard hook, updates CLAUDE.md. One command per machine.

03

#### / Index The Project

trace-mcp add

Detects frameworks, indexes the codebase, registers the project. The graph stays incrementally fresh from here on.

~/projects/my-app ready
# 1. see your waste — ~5 minutes, no setup $ npx trace-mcp benchmark . [OK] indexed 1,247 files / 8,392 symbols [BENCH] impact analysis 49,141 → 1,856 tokens (96.2% less) [BENCH] call graph 178,345 → 9,285 tokens (94.8% less) [BENCH] type hierarchy 94,762 → 855 tokens (99.1% less) [OK] total recomputation: up to ~99% per call # 2. wire trace-mcp into your agent $ npx trace-mcp init [OK] claude code / cursor / windsurf configured [OK] guard hook installed [OK] claude.md updated # 3. agent now reuses the graph instead of re-reading > get_change_impact("app/Models/User.php") [READY] 1 call → 23 affected symbols, 4 tests, 1 decision
014 / Faq

## Common questions.

#### Do I need API keys or a cloud account?

+
No. trace-mcp is fully local. The default semantic search uses a bundled ONNX model (~23 MB, downloaded once on first use). For optional LLM summarization you can plug in Ollama or OpenAI — but everything else runs without external services.

#### Where does the index live?

+
In `~/.trace-mcp/` — one SQLite database per project, plus shared decision and topology databases. Nothing is written into your project directory unless you opt in with `.traceignore` or `.trace-mcp/.config.json`.

#### Does it work for monorepos and multi-service codebases?

+
Yes. `subproject_add_repo` links separate repositories into a unified topology. Cross-service impact analysis traces API calls across service boundaries with confidence scores.

#### How does it stay up-to-date?

+
A file watcher (300ms debounce) reindexes changed files incrementally. Content-hashed — unchanged files are skipped. The graph is always current without manual reindex.

#### What about my framework? Is it supported?

+
81 languages and 58 framework integrations ship out of the box. For unsupported frameworks, the plugin API is open — write a custom plugin in TypeScript, register it via `~/.trace-mcp/plugins/`. Most plugins are ~200–500 lines.

#### Is it safe to run on production codebases?

+
All MCP tools are read-only by default. Refactoring tools (`apply_rename`, `apply_codemod`) require explicit confirmation and support dry-run preview. The guard hook blocks accidental destructive operations from your AI agent.
/ The Category

## Recomputation → Reuse.
The execution layer for AI systems.

AI systems don't scale because they recompute instead of reuse. Every turn costs tokens, latency, and reasoning quality on work the agent has already done. trace-mcp turns recomputation into a precomputed, queryable structure — starting with code, where the noise is loudest, and extending to anywhere agents pay twice for the same answer.

94%
/ Open Source · Mit License · Zero Api Keys

## Stop burning tokens.
Make AI work at scale.

~40–50% lower token usage on average in production. Up to 94–99% in structured tasks. One install. Every project. Every AI agent that speaks MCP.

Get started in minutes → Star on github