/ 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.

Built by a Y Combinator alum 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

Languages

tree-sitter + lsp

Integrations

15 fw / 7 orm / 13 ui / 23 other

MCP Tools

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.

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

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

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.

/ 01Computed once, queried many times — a graph, not a text index that gets re-ranked every turn.
/ 02Framework-aware edges across 58 integrations — routes, ORMs, views, DI captured up front, not rediscovered from raw files.
/ 03Tools that return answers, not snippets to read — get_change_impact, get_call_graph, find_usages over a precomputed structure.
/ 04Reuse 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.

Project overview screen showing indexing status, file and symbol counts, and coverage

Projects list with a repository indexing in progress

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.

/ 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.

/ 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.

/ 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.

/ 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