Crumbtrail documentation

Introduction

Crumbtrail has two packages. crumbtrail-core is the browser SDK: it runs the collectors and the silent-signal detectors inside your app. crumbtrail-node is the local server: capture ingest, Express middleware, the CLI, and an MCP server that exposes finished sessions as tools your coding agent can call. Adopt only what you need.

Quickstart

On Crumbtrail Cloud? Create an account and the in-app setup wires your app in one guided pass. The steps below run the local capture server yourself — no account needed.

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 monitoring: 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

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, automatically.

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 pre-computed 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

Two ways to get your stack into a bundle — stream it in, or let Crumbtrail pull it at ticket time. Pick per source; most teams run both.

Stream it in — SDK & OTLP

When a ticket arrives, Crumbtrail queries the observability tools you already run inside the located incident window and folds the hits into the same ranked bundle — no re-instrumentation. Fetches are read-only and zero-copy: only the derived bundle is stored, never the raw provider data. A missing join key degrades to an honest gap, never an error.

See the full capture pipeline for spans, database diffs and MCP.

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