Crumbtrail documentation

Introduction

The SDKs and the CLI are open source, MIT licensed, and published to npm — the source lives in CrumbtrailDev/crumbtrail-js. crumbtrail-core is the browser SDK: it runs the collectors and the silent signal detectors inside your app. crumbtrail-node is the server: capture ingest, Express middleware, and an MCP server that exposes finished sessions as tools your coding agent can call. Everything else — React, React Native, Tauri — builds on those two. Adopt only what you need; none of it requires a Crumbtrail account.

Quickstart

One command does the whole setup. The wizard detects your framework, installs the right package, injects the Crumbtrail.init() call into your entry file, and waits for your first real event before it calls itself done:

npx crumbtrail

In a monorepo, run it from the repo root — it scans every workspace, shows you what it found, and wires the ones you pick. Prefer to do it by hand? The rest of this section is that same setup, unrolled.

1. Install and start the server

pnpm add crumbtrail-core crumbtrail-node
# start the local capture + MCP server on :9898
# (sessions land under ~/.crumbtrail/sessions)
npx crumbtrail-server serve

On pnpm 10+? Its supply chain check queries the registry for every dependency, and a version that was just published can fail a fresh lockfile with ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION until it ages in. If you hit that for crumbtrail-core, add it to minimumReleaseAgeExclude in pnpm-workspace.yaml (pnpm does not read this key from .npmrc).

2. Initialize in the browser

import { Crumbtrail } from "crumbtrail-core";

// "passive" — embedded end user capture: collectors on,
// silent signal detection enabled, no widget.
Crumbtrail.init("passive");

// …or configure explicitly:
Crumbtrail.init({
  httpEndpoint: "http://localhost:9898",
  autoFlagOnSignals: true,
});

3. Verify end to end

Use your app as normal, then let the doctor prove the pipeline — capture, correlation, and MCP readability — before you trust it:

npx crumbtrail-server doctor

Packages

Six published packages, all MIT licensed and all in one repo. Read the source before you ship it — that's the point of shipping it this way.

Collectors

A collector subscribes to one source of browser events. Each is a boolean in Crumbtrail.init(); the full, light and passive presets pick sensible sets so you rarely toggle them by hand.

Detection

The SDK keeps a rolling buffer of the last five minutes of session events. Four behavioral detectors watch that stream for the signals of a user giving up — none of them requires an exception. When one fires, Crumbtrail flags the reproduction window around it as a bug without further action.

Enabled by autoFlagOnSignals — on in the passive and fullpresets. Every threshold above is a config key; tune them to your app's rhythm.

Session format

Each session is a directory of plain files you fully own: events.ndjson (the raw, append only log), a manifest, and a precomputed evidence index including a normalized, redacted search.jsonl. Agents read the index; the raw log stays cold.

{"t":1751818000123,"k":"clk","d":{…}}
{"t":1751818000304,"k":"net.req","d":{…}}
{"t":1751818000451,"k":"net.res","d":{…}}
{"t":1751818000460,"k":"err","d":{…}}

Every event shares t (Unix milliseconds), k (a kind code — clk, net.req, con, err, db.diff, …) and d, the collector specific payload.

Integrations

Send evidence from your stack into a self hosted capture server. Choose the source that fits your application.

SDK and OTLP

MCP for agents

The same binary serves MCP over stdio — so your coding agent pulls the evidence itself instead of guessing from a screenshot.

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

More than thirty tools in total. The ones you'll reach for most: getFixContext (the ranked causal window for one failure), getRegressionContext (what diverged between two releases), getEvidence, listBugs, listSessions and getEvents.

CLI reference

One binary, crumbtrail-server. Run any command with --help for flags.

Self hosting

The capture server is a single process with no database. It appends plain files to disk. Run it anywhere Node runs; set CRUMBTRAIL_AUTH_TOKEN to require a token on ingest.

CRUMBTRAIL_AUTH_TOKEN=<token> \
npx crumbtrail-server serve --port 9898 --output /var/crumbtrail/sessions

FAQ