Give your coding agent bug context in one evening

Your coding agent can read your repository. It cannot read what your user did five minutes before they filed the bug. This walkthrough closes that gap on a side project in an evening, using only the open source packages.

What you will have at the end

A local capture server holding real sessions from your app, and your coding agent able to ask it questions: what was the last failure, what did the user actually click, which request returned the error, what changed between the release that worked and the one that did not.

Step one: start the capture server

The setup wizard detects your framework, installs the right package, injects the initialization call into your entry file, and waits until it has seen a real event before it declares itself done. Run it from your repository root.

npx crumbtrail

In a monorepo it scans every workspace, shows you what it found, and wires only the ones you pick. It never edits more than one file, it shows you every change first, and if it cannot edit safely it prints the snippet for you to paste. If you would rather do it by hand, the two steps it automates are these.

pnpm add crumbtrail-core crumbtrail-node
npx crumbtrail-server serve

The server listens on port 9898 and writes sessions under a local directory. Each session is a folder of plain files: an append only event log, a manifest, and a precomputed evidence index. Nothing is a proprietary blob you cannot read.

Step two: initialize in the browser

import { Crumbtrail } from "crumbtrail-core";

// "passive" turns the collectors on, enables silent signal
// detection, and shows no widget to the end user.
Crumbtrail.init("passive");

That single call starts the collectors. Clicks, keystrokes with sensitive fields redacted, console output, fetch and XHR with timings and status, uncaught errors and rejections, scroll and tab visibility, cookie and storage writes, timing marks, and the feature flags and build metadata in force at the time.

Text nodes and input values are masked by default. You opt specific elements back in rather than opting sensitive ones out, which is the safer default when you are pointing this at anything real.

Step three: prove the pipeline before you trust it

Use your app the way a user would, then let the doctor command check capture, correlation, and whether an agent can actually read the result. Do this before you build any opinion about the tool, because a silent capture failure looks exactly like a quiet application.

npx crumbtrail-server doctor

Step four: connect your agent over MCP

The same binary speaks MCP over stdio, so a coding agent can retrieve recorded evidence while it works on a bug. Add it to your client config.

{
  "mcpServers": {
    "crumbtrail": {
      "command": "npx",
      "args": ["-y", "--package", "crumbtrail-node", "crumbtrail-server", "serve", "--mcp"]
    }
  }
}

Then ask your agent about a failure instead of describing one. Start with the latest issue, or list sessions and pick one. Ask for the ranked fix context when you want a summary rather than raw events, and walk from the session manifest to the evidence index and into a specific time window only when you need that much detail.

The part that surprises people

Four detectors watch the event stream for a user giving up, and none of them needs an exception to fire. Four or more clicks on the same target inside a second and a half. Four or more requests to one endpoint inside five seconds. Three or more responses over three seconds inside a ten second window. Two or more filled inputs and then the tab hides with no submit.

Those are the bugs nobody reports. The button that silently does nothing, the form that eats an entry, the page slow enough that people quit. They throw no error, so an error tracker never sees them, and the user rarely files a ticket about feeling annoyed. Each threshold is a config key, so you can tune them to your app rather than argue with our defaults.

If you already have telemetry

You do not have to add a second SDK to an app that already exports OpenTelemetry. Point an exporter at the capture server and keep the instrumentation you have.

npm i crumbtrail-node
npx crumbtrail-server serve
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:9898

Set the session identifier as a resource attribute so spans file into the right session, and propagate the W3C traceparent header from the browser so a click in the interface links to the backend error through one trace.

An honest note on scope

One evening gets you capture, correlation, the detectors, and MCP retrieval against a single bug. It does not get you the parts that need time to be worth anything: memory across incidents so a recurrence is recognized months later, and the accumulated tenant playbook. Those need a few weeks of real traffic before they say anything useful.

We think that is the right order to meet the tool in. Run it against a bug you already understand. If the evidence does not change what your agent says, nothing further along would have fixed that.

Where to read the source

Six packages, all MIT licensed, all in one repository at CrumbtrailDev on GitHub. The browser SDK has zero dependencies. Read it before you ship it, which is most of the point of shipping it this way.