root@localhost:~# status: 31 mcp tools loaded, debugger attached

You don't review the diff. // you review the runtime.

An AI agent just rewrote your handler. The diff looks fine. Does the code actually work? Tracegrab sets real breakpoints in your real process, fires a real request, and hands the agent back a diagnosis — not a stack trace it has to guess from.

agent session — mcp://tracegrab
$ auto_debug --scenario checkout.flow.json
→ breakpoints set: 3   calls fired: 2   paused: 4 times

verdict: FAILING — exception thrown on this path

✗ critical  DBTimeout thrown in findItem          items.repo.ts:9
⚠ high      N+1: findItem called 3× in a loop
⚠ high      token cleared (abc123 → '') in getOrders
▲ medium    heap +1.0MB, never reclaimed

callPath:
  CONTROLLER getDashboard
    SERVICE    getOrders
      DB         findItem
$ get the extension source → read the mcp spec

// the actual problem

Agents write code fast. They can't see if it runs.

An LLM reads your source and reasons about what the code should do. It has no eyes on what the code actually does once a request hits a real DB, a real cache, a real race condition. That gap is where "looks right, ships broken" comes from.

> no fake traces

Real breakpoints in vscode.debug, on your actual process. Not a sandboxed re-execution, not a mocked call graph — the live thing, paused mid-flight.

> structured, not stdout

Output is a typed verdict + ranked findings an agent can branch on programmatically. No regex-ing a console dump to find the bug.

> the agent drives itself

31 MCP tools over stdio. No copy-pasting logs back and forth between your terminal and a chat window.

> closes the loop

save_trace → ship the fix → compare_traces. The agent proves REGRESSION / CHANGED / EQUIVALENT instead of asserting "should be fixed now."

// mcp://tracegrab

Built MCP-native. Not bolted on.

Any MCP client — Cursor, Claude Code, Kiro, your own agent loop — gets the same 31-tool surface. Register once:

~/.cursor/mcp.json 
{ "mcpServers": { "tracegrab": {
  "command": "node",
  "args": ["/ABS/PATH/tracegrab/mcp/flow-mcp.mjs"],
  "env": { "FLOW_WORKSPACE": "/ABS/PATH/to/target/repo" }
} } }

auto_debug()

One call: set breakpoints, drive the scenario, build the call map, run every detector, return a verdict. The whole investigation, one round trip.

get_pause_state() → debug_step()

Granular control when auto isn't enough: read a live pause, inspect scope, mutate a variable to force a branch, step, continue. Read → decide → act.

start_headless_session()

No VS Code, no panel — the same steer loop runs in CI, a container, or a pure-agent box. Tested with Node and Python (debugpy) only; other languages are unverified. more →

save_trace() / compare_traces()

Baseline a run, diff a later one — REGRESSION / CHANGED / EQUIVALENT — plus behavior contracts an agent (or CI) can gate on.

get_call_map() / get_memory_timeline()

Structured runtime truth: nested calls, boundary data, heap deltas, variable values, Mermaid export. Something to reason over, not a screenshot.

get_capabilities() / get_audit_log()

The agent probes what's possible before committing. Every live mutation is logged. Secrets redacted, propose-then-confirm by default.

Ships with an AGENTS.md the agent reads unprompted — it tells the agent when to reach for this (a bug report, a ticket, "why does endpoint X do Y") and how to turn that into breakpoints + a run. Full spec: docs/AGENT_AUTOMATION.md.

// receipts

What the agent (and you) actually see

Captured from the real built webview — verdict first, evidence around it.

Full editor view: source with breakpoints beside the debugger panel showing the LOOKS OK verdict, call map, memory timeline and live inspector

what the agent actually sees

Source + breakpoints on the left; the live panel on the right — verdict, call map, memory, and the paused scope the agent reads over MCP.

Run-centric workspace with verdict, findings, call map and inspector

verdict + call map

Ranked findings, nested call tree, run history, live inspector — in one view.

Prove tab showing a regression comparison and a failing contract

prove.diff()

Baseline vs. later run: REGRESSION / CHANGED / EQUIVALENT, plus a contract check.

Request editor with headers, body and extraction fields

request editor

Method, URL, headers, body, response-value extraction. Reorder, duplicate.

First-run onboarding offering three capture paths

cold start

Observe a Postman request, run a scenario, or let an agent/CI collect — your pick.

// not another debugger

DAP-over-MCP gives you frames. This gives you a verdict.

generic dap-over-mcptracegrab
modelstep / inspect / evaluaterequest-shaped call map + diagnosis
outputraw frames & variablesverdict + ranked findings
http flow aware—✓ controller→service→db
n+1 / silent-clear / heap—✓ auto-detected
mock the db for a run—✓ boundary injection
headless (no ide)—✓ ci-safe

// get running

How to install

Tracegrab is two pieces that work together: the extension (the panel you watch) and the MCP server (how your AI agent drives it). You install both — skip the MCP step and the agent has no tools, which is the single most common reason people get stuck.

> where to get it

Published on both registries — install straight from your editor:
VS Code → VS Code Marketplace.
Cursor / Kiro / Windsurf / VSCodium → Open VSX.

> what you need

Node.js 18+, an MCP-capable editor (VS Code / Cursor / Kiro / Windsurf) or any MCP agent. Nothing to build — install from the marketplace.

// step 1 — install the extension (the panel)

Open your editor's Extensions panel, search “tracegrab”, and click Install — VS Code pulls from the Marketplace, Cursor / Kiro / Windsurf / VSCodium from Open VSX. Or from the command line:

$ code --install-extension TraceGrab-KaranSinha.tracegrab        # VS Code
$ cursor --install-extension TraceGrab-KaranSinha.tracegrab      # or: kiro / windsurf / codium

Prefer the raw artifact or building from source? .vsix on GitHub Releases, build steps in Contributing. After installing, run Developer: Reload Window.

// step 2 — wire up MCP (give the agent the tools) ← don't skip this

The extension alone gives you the panel. For an AI agent to take control — set breakpoints, fire the request, step and read the pause for you — it needs the 31 MCP tools. Point your agent's MCP config at the server flow-mcp.mjs, with FLOW_WORKSPACE set to the project you want to debug, using an absolute path. (Clone the repo, or locate it inside the installed extension folder — mcp/flow-mcp.mjs ships with it.)

~/.cursor/mcp.json · Kiro: mcp.json · or your agent's MCP config 
{ "mcpServers": { "tracegrab": {
  "command": "node",
  "args": ["/ABS/PATH/tracegrab/mcp/flow-mcp.mjs"],
  "env": { "FLOW_WORKSPACE": "/ABS/PATH/to/the/repo/you/debug" }
} } }

Confirm the agent actually has the tools before you rely on it — this is the step whose absence leaves you stuck. After saving the config, restart/reload your editor so it respawns the MCP server, then ask the agent: "call get_debug_status". If it answers with a status verdict, the tools are live. If it says the tool doesn't exist, the config isn't being read — re-check the absolute path to flow-mcp.mjs and that your editor reloaded.

// first run

Getting started

New here? Read the one concept below first — it's the thing that trips everyone up — then follow the five steps against the bundled demo app.

// the one concept to get first: two ways to drive

panel (manual)ai agent (mcp)
who drivesyou, clicking in the panelthe agent, via MCP tools
set breakpointsclick the editor gutterask it ("break at the recursion line")
fire the requestrun curl yourselfask it to fire the call
step / inspectbuttons in the panelit steps and reports back

These aren't two installs — it's the same debug session. The agent can take over a session you started, and you watch it live in the panel at the same time. A first-time user won't know this, so the steps below walk the panel path first, then hand the whole thing to the agent at the end — that handoff is the point of the tool, so it needs the MCP setup from install step 2 done first.

  1. Install prerequisites (once). For the Node demo: cd examples/demo-target && npm install — Node's debugger is built in, nothing else needed. For the Python demo: debugpy must live in the interpreter your launch config uses; on Homebrew/PEP 668 Python make a venv — python3 -m venv .venv then .venv/bin/python -m pip install debugpy — and point the Python config at .venv/bin/python.
  2. Confirm your agent has the MCP tools (if you did the MCP setup in install step 2). Ask the agent "call get_debug_status". A status verdict back = tools live, you're ready for the agent path. "Tool doesn't exist" = the MCP config isn't wired — fix that first, or the agent can't drive anything and you'll be stuck. Panel-only (no agent)? Skip this.
  3. Start the app the right way — this is the #1 mistake. Open examples/demo-target, then Command Palette (Cmd+Shift+P) → Tracegrab: Start Debugging (launch + panel) → pick Debug demo-target (Node). Do not run node server.js in a terminal, don't F5 a non-Tracegrab config, and don't use plain Tracegrab: Start (that opens the panel only, it doesn't launch the debugger). Only this command creates a session Tracegrab owns — start it any other way and the panel can look "running" while Tracegrab and the agent can't actually see or drive it.
  4. Confirm it attached. The terminal prints Debugger attached and demo-target listening on http://127.0.0.1:3000, the status bar turns orange, and the panel opens. The panel is empty until a request pauses — that's expected, not a bug.
  5. Set a breakpoint, then fire a request at the local server. Click the gutter in server.js — good lines: 37 (for-loop body), 50 (recursive self-call), 40 (discount branch). The request can come from anything that can hit http://127.0.0.1:3000 — the server runs on your own machine, so it's a plain local HTTP call: curl http://127.0.0.1:3000/orders/A1/loop, a Postman/Insomnia request to the same URL, a browser tab, or the panel's own Run scenario button. The request hanging is the success signal — it's paused at your breakpoint and the call map + inspector fill in. Continue in the panel to finish it. Other routes to try: /orders/A1/recursive (recursion as a ↻ ×N node), /orders/A2/loop (empty items, total 0), /orders/ZZZ/loop (404, no pause).
  6. The payoff — let the AI agent run the whole test for you. This is what Tracegrab is for. With the session running and MCP wired (steps 2–3), you don't touch the gutter or curl at all. Tell the agent in chat: "Set a breakpoint at the recursion line in server.js, call /orders/A1/recursive, then show me the call map and the paused variables." It sets the breakpoint, fires the request, pauses, reads the live scope, steps, and reports the diagnosis back — driving the same session you're watching, so the pauses light up in your panel in real time. It auto-takes-over the child session that actually pauses, so there's no manual session switch. If instead the agent reports NOT RUNNING, the session wasn't started via step 3's command, or MCP's FLOW_WORKSPACE points at a different folder than the one you opened — the two must be the same repo.

// if something's off (the exact traps we hit)

  1. The agent says the tool doesn't exist / can't call get_debug_status. MCP isn't wired. Add the mcpServers block (install step 2) pointing at mcp/flow-mcp.mjs with an absolute path, then reload your editor so it respawns the server. Without this the agent has no tools and cannot drive anything.
  2. Panel says "running" but the agent says NOT RUNNING. Either the server was started the wrong way (terminal, auto-attach, or Tracegrab: Start) — relaunch via Start Debugging (launch + panel) — or MCP's FLOW_WORKSPACE points at a different folder than the one open in the editor. Both sides must be the same repo.
  3. Port already in use (EADDRINUSE). An old process is holding 3000 (or 3001 for Python). Stop it first.
  4. The request returns immediately instead of hanging. No breakpoint is set, or it's on a line that didn't run (e.g. a 404 path). Set one on a line that executes.
  5. Python panel stays empty. debugpy isn't in the interpreter the config launched — install it in that exact environment, or point the config at your .venv.
  6. Just updated the extension? Run Developer: Reload Window so the new build loads before you test.

// no ide, no panel

Headless mode: MCP without the window

The panel and MCP are two halves of the same tool. In the normal flow the panel (the extension's UI) is what you watch, and MCP is how the agent drives — together they give you the automation. In headless mode there is no panel: no VS Code, no window to look at. The agent still sets breakpoints, fires calls, reads pauses, and returns a verdict entirely over MCP — which is what makes it work in CI, a container, or a pure-agent box.

> panel = eyes, mcp = hands

With the IDE, you see the live call map and inspector while the agent (or you) drives. Headless keeps the hands and drops the eyes — same session model, no UI.

> start it with one call

start_headless_session() launches the target under the debugger with no F5 and no panel. The rest of the MCP loop — breakpoints, scenario, pauses, verdict — is identical to the IDE path.

> tested languages

Verified against Node and Python (debugpy) only. Other languages are not verified — they may work via their DAP adapter, but we haven't tested them and don't claim support.

// hack on it

Contributing

VS Code extension host (src/, Node/TS) + a React webview (webview-ui/) + a zero-dep MCP server (mcp/). Full map in CONTRIBUTING.md.

$ git clone https://github.com/sinhaKAN-ra/tracegrab && cd tracegrab
$ npm install
$ npm run build        # webview (Vite) then host (tsc)
$ npm test             # host-logic + call-tree + safety suites

Gates a PR must pass green:

  1. npm run compile — host TypeScript, 0 errors.
  2. npm run build --prefix webview-ui — webview build, 0 errors.
  3. cd webview-ui && npx oxlint src — 0 warnings, 0 errors.
  4. npm run lint:boundaries — public core stays self-contained and strategy-free.

One logical change per PR. Never commit secrets, .vsix artifacts, or .flow-debugger/ runtime output. Found a bug or want to propose a feature? Open an issue, or email nomore.report@gmail.com directly.