Recomputation → Reuse v… MIT

Precomputed code intelligence for AI coding agents

trace-mcp is an MCP server that indexes your repository once so AI coding agents stop re-reading the same files — 90.6% fewer input tokens to review a pull request.

Download ↓

macOS Windows all downloads

Open source 100% local Claude Code Cursor Codex Windsurf

90.6% Fewer input tokens to review a pull request — median over 60 merged PRs in 6 open-source repositories

~40–50% Average token reduction across mixed agent workloads

up to 2× Effective context capacity per session

The first figure is measured on other people's code — 60 merged pull requests, SHAs pinned, run script and the 5 cases where it barely paid off all published: PR review context benchmark. The other two come from our own instrumentation, measured against baseline agent runs that re-read files and re-traverse dependencies on every turn — what that figure covers, and where it is roughly zero.

Built by a Y Combinator alum License Open source · MIT GitHub stars … watching

/ Built For Modern AI Coding Stacks

MCP Claude Code Cursor Windsurf Claude Desktop VS Code

Languages

tree-sitter + lsp

Integrations

frameworks, ORMs, UI & more

MCP Tools

read-only or audited

PR Context

90.6%

median over 60 merged PRs, code we don’t own

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. That repeated work is most of what a long session costs in tokens and latency.

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.

Measure what the agent reads, explain why it reads it twice, remove the repeated work, and keep it from coming back.

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.

What the agent queries instead of your files.

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. 87 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 to a working index.

Connect the repo, let it index, point your MCP client at it. The graph then 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, 87 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 178 mcp tools local sqlite

Expose to your agents

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

How the indexer, graph and plugin system fit together: Architecture → · every language and framework it understands: Supported stack →

005 / Core Capabilities

The five calls agents reach for first.

Five tools from a surface of 178 — 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.

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

178 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

The difference shows up on the second question, not the first.

Side-by-side tables against every comparable tool: Comparisons →

007 / Differentiation

Why a graph beats a better search index.

/ 01Computed once, queried many times — a graph, not a text index that gets re-ranked every turn.
/ 02Framework-aware edges across 87 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.

A text index is re-ranked on every query. A graph is computed once and traversed — so the second question about a repo costs a fraction of the first.

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.

trace-mcp app — project Overview with index status, file and symbol counts, and dependency coverage

trace-mcp app — project Overview with index status, file and symbol counts, and dependency coverage, dark appearance

trace-mcp app — Workspace dashboard listing indexed projects with their file, symbol and coverage metrics

trace-mcp app — Workspace dashboard listing indexed projects with their file, symbol and coverage metrics, dark appearance

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

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

011 / Ecosystem

87 integrations. 81 languages.

Each integration adds framework-specific edges — routes, components, migrations, queries — not just syntax parsing. The plugin API is open; most plugins are 200–500 lines of TypeScript.

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

012 / Install

Three commands. No config, no signup.

Install globally, wire trace-mcp into your AI agent, then register each project. Requires Node.js 20+. No API keys — embeddings ship with the binary and everything stays local.

/ Install Globally

npm install -g trace-mcp

Installs the trace CLI from the trace-mcp package (the older trace-mcp command keeps working). ~30 seconds. Requires Node.js 20 or newer. Prefer pnpm or yarn? pnpm add -g trace-mcp / yarn global add trace-mcp work too.

/ Wire Into Your Agent

trace init

One-time global setup. Auto-detects installed MCP clients (Claude Code, Cursor, Windsurf, Claude Desktop, Codex, JetBrains AI, …), wires trace into each, installs the guard hook, and adds routing rules to ~/.claude/CLAUDE.md. Run once per machine.

/ Register Each Project

cd ~/projects/my-app && trace add

Detects frameworks, builds the per-project index, registers the project. The file watcher keeps the graph incrementally fresh from here on. Re-run in every repo you want trace to understand.

~/projects/my-app ready

# 1. install the CLI globally (~30 seconds) $ npm install -g trace-mcp [OK] trace-mcp@latest installed (commands: trace, trace-mcp) # 2. one-time setup — wire trace into your AI agent $ trace init [OK] claude code / cursor / windsurf configured [OK] guard hook installed [OK] claude.md updated # 3. register the current project for indexing $ trace add [OK] detected frameworks: typescript, vue, vitest [OK] indexed 1,247 files / 8,392 symbols [READY] file watcher armed — graph stays fresh # done — your agent now reuses the graph instead of re-reading > get_change_impact("src/models/User.ts") [OK] 1 call → 23 affected symbols, 4 tests, 1 decision

Stdio vs HTTP, semantic search, .traceignore and every other option: Configuration →

013 / Faq

Common questions.

What is the best MCP server for giving Claude Code codebase context?

trace-mcp is built specifically for this: it indexes a codebase once into a local dependency graph (SQLite + FTS5, tree-sitter parsing across 81 languages) and exposes 178 MCP tools — outline, symbol lookup, call graph, impact analysis, dead code detection — so Claude Code queries precomputed structure instead of re-reading files every turn. It runs entirely locally with no API keys, works with 87 framework integrations, and typically cuts token usage 40–50% versus raw file reads while producing more consistent answers as the codebase grows. It's open source (MIT), installs with npm install -g trace-mcp, and works over stdio or HTTP with any MCP-compatible client, including Claude Code, Cursor, and Windsurf.

How do I reduce Claude Code token usage?

The biggest lever is stopping repeated full-file reads: instead of having the agent re-read and re-traverse the same files every turn, give it precomputed code intelligence it can query directly. trace-mcp does this by indexing your repository once into a dependency graph, then exposing MCP tools like get_outline, get_symbol, find_usages, and get_change_impact that return only the relevant symbols and relationships instead of whole files. Teams typically see 40–50% fewer tokens per session, since navigation, dependency lookups, and impact analysis become single tool calls instead of multi-file exploration. Install it with npm install -g trace-mcp, point Claude Code at it over MCP, and it indexes locally with no cloud calls or API keys required.

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 87 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.
Precomputed code intelligence for AI coding agents.

AI systems pay repeatedly for work they have already done: every turn re-derives structure the agent held a few steps earlier. trace-mcp precomputes that structure once and serves it over MCP. Code is where the repetition is most expensive today, which is where we started.

/ Open Source · Mit License · Zero Api Keys

Index once,
query for the rest of the session.

~40–50% lower token usage on average, and up to 94–99% on structured tasks. One install, and every MCP-capable agent in the project gets the same graph.

Get started in minutes → Star on github