trace-mcp

<!-- Header images are generated — `node scripts/gen-readme-banner.mjs` re-renders them from docs/_data/counts.yml and docs/_data/pr_context_bench.json. Never retouch a PNG by hand: the numbers in it would stop tracking the data. PNG @2x rather than SVG because GitHub renders README images in an isolated context where an SVG's @font-face never loads and Space Grotesk falls back. The narrow cut is for phones: GitHub scales the 1200px banner into a ~390px column, which drops the tagline to 8px. Order matters — the first matching <source> wins, so the max-width pair has to stay above the theme source. The missing space in `(prefers-color-scheme:light)` on the narrow source is deliberate: GitHub's <themed-picture> substring-matches the spaced form and, for a reader who pinned Light in Appearance, rewrites that source's media to match every viewport — which would put the phone cut on a 750px desktop. --> <p align="center"> <picture> <source media="(max-width: 500px) and (prefers-color-scheme:light)" srcset="docs/images/readme/banner-narrow-light.png" /> <source media="(max-width: 500px)" srcset="docs/images/readme/banner-narrow-dark.png" /> <source media="(prefers-color-scheme: light)" srcset="docs/images/readme/banner-light.png" /> <img src="docs/images/readme/banner-dark.png" width="750" alt="trace-mcp indexes what your agent keeps re-reading, and serves the answer instead. Context to review one pull request: 13,595 tokens without trace-mcp, 3,291 with it — 72.7% less, median over 60 merged PRs in 6 open-source repos that are not ours. 182 tools, 81 languages, 88 framework integrations, your code stays local, MIT." /> </picture> </p> <!-- The three buttons carry their own background plate and sit flush against each other, so they continue the banner instead of floating on GitHub's canvas. Keep the anchors on one line: any whitespace between them paints a seam. There is no `width` attribute here on purpose. One `width` serves every viewport, so it can pin the desktop row (3 x 250 = 750, the banner's width) or let the phone cut fill the column, never both. The size therefore comes from srcset density instead: the 1600px desktop art declared `6.4x` lays out at exactly 250, and the 2000px phone art declared `4x` lays out at 500 — wider than any phone column, so `max-width: 100%` clamps it to the full width and the empty margin either side of the plate disappears. GitHub strips srcset from <img> while keeping it on <source> — measured on a live PR page — so the last <source> carries no media at all and always matches. That is what sizes the default dark view; the <img> is only ever reached by a renderer that drops <picture> entirely. --> <p align="center"><a href="https://github.com/nikolai-vysotskyi/trace-mcp/releases/latest"><picture><source media="(max-width: 500px) and (prefers-color-scheme:light)" srcset="docs/images/readme/btn-macos-narrow-light.png 4x" /><source media="(max-width: 500px)" srcset="docs/images/readme/btn-macos-narrow-dark.png 4x" /><source media="(prefers-color-scheme: light)" srcset="docs/images/readme/btn-macos-light.png 6.4x" /><source srcset="docs/images/readme/btn-macos-dark.png 6.4x" /><img src="docs/images/readme/btn-macos-dark.png" alt="Download for macOS — Apple Silicon, Intel, .dmg" /></picture></a><a href="https://github.com/nikolai-vysotskyi/trace-mcp/releases/latest"><picture><source media="(max-width: 500px) and (prefers-color-scheme:light)" srcset="docs/images/readme/btn-windows-narrow-light.png 4x" /><source media="(max-width: 500px)" srcset="docs/images/readme/btn-windows-narrow-dark.png 4x" /><source media="(prefers-color-scheme: light)" srcset="docs/images/readme/btn-windows-light.png 6.4x" /><source srcset="docs/images/readme/btn-windows-dark.png 6.4x" /><img src="docs/images/readme/btn-windows-dark.png" alt="Download for Windows — .exe installer" /></picture></a><a href="https://www.npmjs.com/package/trace-mcp"><picture><source media="(max-width: 500px) and (prefers-color-scheme:light)" srcset="docs/images/readme/btn-npm-narrow-light.png 4x" /><source media="(max-width: 500px)" srcset="docs/images/readme/btn-npm-narrow-dark.png 4x" /><source media="(prefers-color-scheme: light)" srcset="docs/images/readme/btn-npm-light.png 6.4x" /><source srcset="docs/images/readme/btn-npm-dark.png 6.4x" /><img src="docs/images/readme/btn-npm-dark.png" alt="Install via npm — npm install -g trace-mcp" /></picture></a></p> <p align="center"> _{<b>WORKS WITH</b> &nbsp;&middot;&nbsp; Claude Code &nbsp;&middot;&nbsp; Cursor &nbsp;&middot;&nbsp; Codex &nbsp;&middot;&nbsp; Windsurf &nbsp;&middot;&nbsp; Zed &nbsp;&middot;&nbsp; any MCP client} </p> <!-- The banner carries this sentence as a picture; this line carries it as text, so search and screen readers get the same claim. Keep the two in sync, and keep both verbatim with the hero on trace-mcp.com and with docs/_config.yml — ops/positioning.md holds the sentence. The boundary line under it is not a footnote: it travels with the claim wherever the claim goes, including the one declinable exception (TRA-979) — keep that clause verbatim with the hero too. --> <p align="center"> <strong>trace-mcp indexes what your agent keeps re-reading, and serves the answer instead.</strong><br /> <strong>72.7% fewer input tokens</strong> to review a pull request &mdash; median over 60 merged pull requests in open-source repos we don't own. </p> <p align="center"> _{We change configuration you could change yourself. We do not patch your client's binary, intercept its traffic, or rewrite its files. One declinable exception: the Max tier's <a href="https://trace-mcp.com/what-trace-init-installs.html#the-tweakcc-pairing-and-the-line-it-sits-next-to">tweakcc pairing</a> runs a third-party patcher for you.} </p> <p align="center"> <a href="https://github.com/nikolai-vysotskyi/trace-mcp/actions/workflows/ci.yml"><img src="https://github.com/nikolai-vysotskyi/trace-mcp/actions/workflows/ci.yml/badge.svg?branch=master" alt="CI" /></a> <a href="https://www.npmjs.com/package/trace-mcp"><img src="https://img.shields.io/npm/v/trace-mcp" alt="npm version" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License" /></a> </p>

npm install -g trace-mcp   # MCP server, no app
trace init                 # wire it into your agent, once per machine
trace add                  # index the repo you are in

72.7% fewer input tokens to review a pull request — median over 60 merged PRs in six repos that are not ours, 13,595 → 3,291 per pull request. Method and reproduction →

_{Measured at trace-mcp 3.23.2 (cb8ab30c) on 7 September 2026 — a result from that build, not a claim about the current one. What it set out to measure, the bar it had to clear and the verdict: preregistration.}

Cheaper is not the same as better, so the same 60 pull requests were reviewed twice and scored blind. The trace-mcp arm understood the change in 67% of them against 65% for naive file loading, at 0.80 false positives per PR against 0.58. Quality half of the benchmark →

<p align="center"> <img src="docs/images/app-graph.webp" alt="trace-mcp app — GPU graph explorer visualizing symbol connections, light appearance" width="820" height="512" loading="lazy" /> <br/> _{The <a href="#desktop-app">desktop app</a>: a GPU graph explorer over the same index the MCP server serves.} </p>

---

The problem

AI agents pay repeatedly for work they have 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.

trace-mcp builds a framework-aware graph of your codebase once, then serves it through MCP so the agent reasons from a precomputed structure instead of brute-reading the repo. Ask "what breaks if I change this model?" — instead of 80 Grep calls and 190 file reads, the agent calls get_change_impact once and gets the blast radius across PHP, Vue, migrations, and DI. 88 framework integrations across 81 languages, 182 tools.

The binding constraint is recomputation, not model capability: token bills, latency, and hallucinations all grow with project size instead of with task complexity. trace-mcp closes the recomputation leak. The graph is built once, kept incrementally fresh, and served to every agent that asks — so the same work isn't paid for over and over.

• Lower cost — fewer tokens per successful answer, on average and at peak
• Lower latency — fewer sequential tool calls, fewer round-trips to the model
• Higher accuracy — less noise in context means fewer hallucinations and stronger first-response correctness
• Production stability — context growth tracks task complexity rather than repository size

We started with code intelligence, where the repetition is most expensive, and the same engine now indexes markdown knowledge vaults (Obsidian, Logseq, plain MD) as a peer domain. Wikilinks, tags, frontmatter, and embeds become graph edges and symbol metadata; search, find_usages, get_change_impact, and apply_rename work identically over both.

---

What trace-mcp does for you

| You ask | trace-mcp answers | How | |---|---|---| | "What breaks if I change this model?" | Blast radius across languages + risk score + linked architectural decisions | get_change_impact — reverse dependency graph + decision memory | | "Why was auth implemented this way?" | The actual decision record with reasoning and tradeoffs | query_decisions — searches the decision knowledge graph linked to code | | "I'm starting a new task" | Optimal code subgraph + relevant past decisions + dead-end warnings | plan_turn — opening-move router with decision enrichment | | "What did we discuss about GraphQL last month?" | Verbatim conversation fragments with file references | search_sessions — FTS5 search across all past session content | | "Show me the request flow from URL to rendered page" | Route → Middleware → Controller → Service → View with prop mapping | get_request_flow — framework-aware edge traversal | | "Find all untested code in this module" | Symbols classified as "unreached" or "imported but never called in tests" | get_untested_symbols — test-to-source mapping | | "What's the impact of this API change on other services?" | Cross-subproject client calls with confidence scores | get_subproject_impact — topology graph traversal | | "What notes link to this concept?" | Backlinks across the vault, with section + alias context | find_usages on a note:<basename> symbol | | "What breaks if I rename this note?" | Every [[wikilink]] and [text](path.md) that references it | get_change_impact — wikilink-aware reverse graph |

Four capabilities that are rare among adjacent tools:

1. Framework-aware edges — trace-mcp understands that Inertia::render('Users/Show') connects PHP to Vue, that @Injectable() creates a DI dependency, that $user->posts() means a posts table from migrations. 88 framework integrations.

2. Code-linked decision memory — when you record "chose PostgreSQL for JSONB support", it's linked to src/db/connection.ts::Pool#class. When someone runs get_change_impact on that symbol, they see the decision. MemPalace stores decisions as text; trace-mcp ties them to the dependency graph.

3. Cross-session intelligence — past sessions are mined for decisions and indexed for search. When you start a new session, get_wake_up gives you orientation in ~300 tokens; plan_turn shows rel