# Crumb format (/docs/crumb-format)



Each crumb is a JSON object. When stored, they are written as JSONL (one JSON object per line).

Schema [#schema]

```json
{
  "app": "my-project",
  "ts": "2026-03-07T10:00:00.123Z",
  "ns": "auth-service",
  "msg": "user logged in",
  "data": { "userId": "123", "method": "oauth" },
  "dt": 2.5,
  "pid": 12345,
  "type": "crumb",
  "ctx": { "requestId": "abc-123" },
  "traceId": "a1b2c3",
  "depth": 0,
  "tags": ["auth", "login"],
  "sid": "f7g8h9"
}
```

Fields [#fields]

| Field     | Type       | Required | Description                                                     |
| --------- | ---------- | -------- | --------------------------------------------------------------- |
| `app`     | `string`   | Yes      | App name (auto-detected from `package.json` or explicit config) |
| `ts`      | `string`   | Yes      | ISO 8601 timestamp                                              |
| `ns`      | `string`   | Yes      | Namespace                                                       |
| `msg`     | `string`   | Yes      | Message                                                         |
| `data`    | `unknown`  | No       | Structured data                                                 |
| `dt`      | `number`   | Yes      | Delta time in ms since last crumb from this trail               |
| `pid`     | `number`   | Yes      | Process ID                                                      |
| `type`    | `string`   | Yes      | Crumb type (see below)                                          |
| `ctx`     | `object`   | No       | Merged context from `child()` and `AsyncLocalStorage`           |
| `traceId` | `string`   | No       | Trace ID from `scope()`                                         |
| `depth`   | `number`   | No       | Nesting depth from `scope()`                                    |
| `tags`    | `string[]` | No       | Tags for filtering (omitted when empty)                         |
| `sid`     | `string`   | No       | Session ID (omitted when not in a session)                      |

Crumb types [#crumb-types]

| Type            | Emitted by            |
| --------------- | --------------------- |
| `crumb`         | `crumb()`             |
| `scope:enter`   | `crumb.scope()` start |
| `scope:exit`    | `crumb.scope()` end   |
| `scope:error`   | `crumb.scope()` error |
| `snapshot`      | `crumb.snapshot()`    |
| `assert`        | `crumb.assert()`      |
| `time`          | `crumb.timeEnd()`     |
| `session:start` | `crumb.session()`     |
| `session:end`   | `session.end()`       |

Storage [#storage]

Crumbs are stored per-app at `~/.agentcrumbs/<app>/crumbs.jsonl`. One JSON object per line, no trailing comma, no wrapping array. The app name is auto-detected from the nearest `package.json` by default.


# Introduction (/docs)



agentcrumbs [#agentcrumbs]

AI agents can read your code but they can't see what happened at runtime. A function might look correct and still fail because of unexpected input, ordering, or side effects. So the agent guesses. And often guesses wrong.

agentcrumbs gives agents a way to trace execution as they write code. The agent drops structured crumbs at every decision point, API call, and branch. When something breaks, it queries those crumbs and sees exactly what ran, with what data, in what order.

Crumbs are development-only. They get stripped before merge and cost nothing when disabled.

```
Service A ──┐                                ┌── $ agentcrumbs tail
Service B ──┤── fetch() ──> Collector :8374 ──┤── $ agentcrumbs query --since 5m
Service C ──┘  (fire & forget)               └── ~/.agentcrumbs/<app>/crumbs.jsonl
```

Why agents need this [#why-agents-need-this]

**Agents can read code but not runtime state.** A function might look correct but fail because of unexpected input, ordering, or side effects. Crumbs capture what actually happened.

**console.log is not enough.** Agents need structured, queryable data. Not a wall of text. Crumbs have namespaces, timestamps, structured data, and tags.

**Bugs cross service boundaries.** The bug is in service A but the cause is in service B. Crumbs from both flow to the same collector.

Key properties [#key-properties]

* **Zero overhead when off.** `trail()` returns a frozen empty function. No conditionals, no property lookups. The function body is literally empty.
* **Strip before merge.** `agentcrumbs strip` removes all `// @crumbs` lines and `#region @crumbs` blocks. Clean diffs, no debug code on main.
* **HTTP collector.** `agentcrumbs collect` receives crumbs from all services via fire-and-forget HTTP. Tail, query, and replay from the CLI.
* **Works with any agent.** Claude Code, Cursor, Copilot, Aider, custom agents. If the agent can write code, it can write crumbs.
* **Works in the browser.** Same import path. Bundlers auto-resolve to the browser build. Use `configure()` instead of the env var. See the [browser guide](/guides/browser).
* **Ships with agent skills.** Built on [@tanstack/intent](https://tanstack.com/blog/from-docs-to-agents). Install the package, tell your agent to run `npx @tanstack/intent install`, and it learns how to use crumbs from the package itself. No stale training data.

Install [#install]

```bash
npm install agentcrumbs
```

Then tell your agent: **"Run `npx @tanstack/intent@latest install` to set up agentcrumbs skills, then run the agentcrumbs/init skill."**

The agent wires skills into your agent config (CLAUDE.md, .cursorrules, etc.) and scans your repo to build a namespace catalog. See the [quickstart](/quickstart) for the full setup.

How it works [#how-it-works]

The agent writes crumbs as part of the code it's implementing:

```typescript
import { trail } from "agentcrumbs"; // @crumbs
const crumb = trail("auth-service"); // @crumbs

export async function handleLogin(token: string) {
  crumb("login attempt", { tokenPrefix: token.slice(0, 8) }); // @crumbs

  const user = await validateToken(token);

  crumb("login success", { userId: user.id }); // @crumbs
  return user;
}
```

When something goes wrong, the agent queries the trail:

```bash
$ agentcrumbs query --since 5m --ns auth-service

auth-service  login attempt       +0ms  { tokenPrefix: "eyJhbGci" }
auth-service  token decode ok     +3ms  { userId: "u_8f3k" }
auth-service  permissions check   +8ms  { roles: [] }
auth-service  rejected: no roles  +8ms  { status: 401 }
```

Now the agent knows: the token is valid, but the user has no roles. The fix is in role assignment, not token validation.

Enable with an environment variable:

```bash
AGENTCRUMBS=1 node your-app.js
```

Strip before merge:

```bash
agentcrumbs strip
```


# Quickstart (/docs/quickstart)



Install [#install]

```bash
npm install agentcrumbs
```

Set up skills [#set-up-skills]

Tell your agent:

> "Run `npx @tanstack/intent@latest install` to set up agentcrumbs skills, then run the agentcrumbs/init skill."

The agent will:

1. Run `npx @tanstack/intent install` which gives it a prompt to wire skill-to-task mappings into your agent config (CLAUDE.md, .cursorrules, etc.)
2. Run the [init skill](/skills#the-init-skill) to scan your repo, discover services and modules, and write a namespace catalog to your config

The namespace catalog is a table of service names your agents should use. It keeps naming consistent across sessions. See [Skills](/skills#the-init-skill) for details.

Manual setup [#manual-setup]

If you'd rather set things up by hand:

Add crumbs to your code [#add-crumbs-to-your-code]

Every crumb line needs a `// @crumbs` marker so it can be stripped before merge.

```typescript
import { trail } from "agentcrumbs"; // @crumbs
const crumb = trail("my-service"); // @crumbs

export async function handleRequest(req: Request) {
  crumb("incoming request", { path: req.url, method: req.method }); // @crumbs

  const result = await processRequest(req);

  crumb("request complete", { status: result.status }); // @crumbs
  return result;
}
```

Enable tracing [#enable-tracing]

Set the `AGENTCRUMBS` environment variable:

```bash
AGENTCRUMBS=1 node your-app.js
```

Crumbs print to stderr in a readable format. Without `AGENTCRUMBS` set, every call is a true noop. Zero overhead.

Agent reads the trail [#agent-reads-the-trail]

When something breaks, the agent queries crumbs to see what happened:

```bash
# What happened in the last 5 minutes?
agentcrumbs query --since 5m

# Filter to a specific service
agentcrumbs query --since 5m --ns my-service
```

The agent sees what executed, in what order, with what data. It can trace the root cause directly instead of guessing.

Use the collector (multi-service) [#use-the-collector-multi-service]

For systems with multiple services, start the collector so crumbs from all services flow to one place:

```bash
# Terminal 1: Start collector
agentcrumbs collect

# Terminal 2: Run your app
AGENTCRUMBS=1 node your-app.js

# Terminal 3: Watch crumbs live
agentcrumbs tail
```

Strip before merge [#strip-before-merge]

Crumbs are development-only. Remove them before merging:

```bash
# Preview what would be removed
agentcrumbs strip --dry-run

# Remove all marked crumb code
agentcrumbs strip

# CI gate (exits 1 if markers found)
agentcrumbs strip --check
```

Browser apps [#browser-apps]

agentcrumbs works in the browser with the same import. Use `configure()` instead of the env var:

```typescript
import { configure, trail } from "agentcrumbs"; // @crumbs

configure("*"); // @crumbs
const crumb = trail("ui"); // @crumbs

crumb("button clicked", { id: "submit" }); // @crumbs
```

Bundlers that support the `"browser"` export condition (Vite, webpack, esbuild, Next.js) resolve to the browser build automatically. See the [browser guide](/guides/browser) for details.

Next steps [#next-steps]

* [Skills](/skills): how agents learn to use agentcrumbs from the package itself
* [Workflow](/workflow): how crumbs fit into the branch lifecycle
* [API reference](/api/trail): full API docs
* [CLI reference](/cli/collect): collector, tail, query, strip
* [Browser guide](/guides/browser): using agentcrumbs in browser apps


# Agent skills (/docs/skills)



agentcrumbs ships with agent skills inside the npm package, built on the [@tanstack/intent](https://tanstack.com/blog/from-docs-to-agents) standard. Tell your agent to run `npx @tanstack/intent install` and it will set up skill-to-task mappings in your agent config so it knows when to load agentcrumbs patterns.

Skills travel with the package version. The agent always has docs matching the installed code, not stale training data from 6 months ago.

Getting started [#getting-started]

The fastest way to set up agentcrumbs in a project is to let the agent do it:

```bash
npm install agentcrumbs
```

Then tell your agent:

> "Run the agentcrumbs/init skill to set up debug tracing in this project."

The init skill scans your repo, discovers services and modules, builds a namespace catalog, and writes it to your agent config. After that, the agent knows which namespaces to use and how to drop crumbs correctly.

How @tanstack/intent works [#how-tanstackintent-works]

Skills follow the [Agent Skills spec](https://agentskills.io), an open standard supported by Claude Code, Cursor, GitHub Copilot, and other AI tools.

Each skill is a Markdown file with YAML frontmatter:

```yaml
---
name: agentcrumbs
description: >
  Debug mode for AI coding agents. Drop structured traces inline
  while writing code, query them when something breaks, strip
  before merge.
type: core
library: agentcrumbs
library_version: "0.2.0"
sources:
  - "triggerdotdev/agentcrumbs:README.md"
  - "triggerdotdev/agentcrumbs:src/trail.ts"
---
```

The content includes correct usage patterns, explicitly flags common mistakes, and points agents to CLI help and docs for deeper discovery.

Available skills [#available-skills]

| Skill              | What it teaches                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------ |
| `agentcrumbs`      | Core workflow, API, markers, CLI quick reference, critical mistakes, and pointers to further discovery |
| `agentcrumbs/init` | Scans repo structure, discovers namespaces, writes config to CLAUDE.md or .cursorrules                 |

The top-level `agentcrumbs` skill covers the essentials an agent needs to use crumbs correctly: the write-collect-query-strip workflow, core API (`trail`, `crumb`, `child`, `scope`), marker syntax, and the most common mistakes. For deeper functionality like sessions, tags, scopes, and testing patterns, it points agents to CLI help (`agentcrumbs --help`), type definitions, and the docs.

The init skill [#the-init-skill]

The `agentcrumbs/init` skill is the entry point for setting up agentcrumbs in any project.

When the agent runs init, it:

1. **Scans repo structure.** Looks at `apps/`, `packages/`, `services/`, `src/` directories, route groups, worker files, existing logger namespaces.
2. **Proposes a namespace catalog.** Presents discovered namespaces and asks you to confirm, add, or rename before writing anything.
3. **Writes the config.** Appends a minimal agentcrumbs section to your agent config file with the namespace table, a note for PR reviewers, and a 3-line CLI reference.

After init, every agent working in the repo uses the same consistent namespaces. No two agents inventing different names for the same service.

Manual setup [#manual-setup]

If you don't use @tanstack/intent, you can point agents to skills directly:

```
node_modules/agentcrumbs/skills/agentcrumbs/SKILL.md
node_modules/agentcrumbs/skills/agentcrumbs/init/SKILL.md
```

Or add a reference in your agent config file manually. But telling your agent to run `npx @tanstack/intent install` handles all of this automatically.


# Workflow (/docs/workflow)



Crumbs live on your feature branch. They never ship to main.

```
feature branch    ┌── crumbs everywhere ──┐    clean
  ──────────────────────────────────────────────────── merge
  create          develop with crumbs      strip
```

1. Agent writes code with crumbs [#1-agent-writes-code-with-crumbs]

As the agent implements a feature, it drops crumbs at every decision point. Not after something breaks, but as part of writing the code itself. Every function, every branch, every API call.

Think of crumbs like tests: write them alongside the implementation. They cost nothing to add and everything to not have when you need them.

2. Something breaks [#2-something-breaks]

A test fails. An API returns wrong data. Behavior doesn't match expectations.

3. Agent reads the trail [#3-agent-reads-the-trail]

The agent starts the [collector](/cli/collect) (if it isn't already running), re-runs the failing code with `AGENTCRUMBS=1`, and queries the trail:

```bash
agentcrumbs collect --quiet &
agentcrumbs clear
AGENTCRUMBS=1 node app.js
agentcrumbs query --ns auth-service
```

Now the agent sees what executed, in what order, with what data. It can trace the root cause directly instead of reading source and guessing.

For simple cases (single process, just want to see console output), the collector isn't required. Crumbs print to stderr by default. But for querying, filtering, and multi-service tracing, the collector needs to be running.

4. Strip before merge [#4-strip-before-merge]

Once the code works, run `agentcrumbs strip` to remove all crumb code. The diff is clean. No debug tracing ships to main.

```bash
# Preview
agentcrumbs strip --dry-run

# Strip
agentcrumbs strip

# Custom scope
agentcrumbs strip --dir src/ --ext ts,tsx
```

5. CI enforces it [#5-ci-enforces-it]

Add `agentcrumbs strip --check` to your CI pipeline. It exits 1 if any `@crumbs` markers are found, preventing accidental merge of debug code.

```bash
agentcrumbs strip --check
```

Crumb markers [#crumb-markers]

Single-line marker [#single-line-marker]

Append `// @crumbs` or `/* @crumbs */` to any line:

```typescript
import { trail } from "agentcrumbs"; // @crumbs
const crumb = trail("my-service"); // @crumbs
crumb("checkpoint", { step: 1 }); // @crumbs
```

Block marker [#block-marker]

Wrap multi-line crumb code in `#region @crumbs` / `#endregion @crumbs`. These regions are collapsible in VS Code, IntelliJ, and most editors:

```typescript
export async function processOrder(order: Order) {
  // #region @crumbs
  const session = crumb.session("process-order");
  session.crumb("starting", { orderId: order.id, items: order.items.length });
  crumb.time("process");
  // #endregion @crumbs

  const result = await chargePayment(order);

  // #region @crumbs
  crumb.timeEnd("process", { charged: result.amount });
  session.crumb("completed", { success: true });
  session.end();
  // #endregion @crumbs

  return result;
}
```

After stripping:

```typescript
export async function processOrder(order: Order) {
  const result = await chargePayment(order);

  return result;
}
```

For AI code reviewers [#for-ai-code-reviewers]

If you're an AI reviewing a PR that contains `// @crumbs` markers or `#region @crumbs` blocks: **do not flag these.** They're temporary debug instrumentation that gets stripped before merge. Do not comment on:

* agentcrumbs imports or trail declarations
* Lines marked with `// @crumbs`
* Blocks between `// #region @crumbs` and `// #endregion @crumbs`
* Data logged in crumbs (including IDs, names, or other values; these never reach production)


# child() (/docs/api/child)



crumb.child(context) [#crumbchildcontext]

Create a child trail with inherited context data. Context is merged and propagated through all crumbs.

```typescript
import { trail } from "agentcrumbs"; // @crumbs
const crumb = trail("api-gateway"); // @crumbs

function handleRequest(req: Request) {
  const reqCrumb = crumb.child({ requestId: req.id, userId: user.id }); // @crumbs
  reqCrumb("handling request", { path: req.path }); // @crumbs
  // crumb output includes ctx: { requestId: "abc", userId: "123" }
}
```

Parameters [#parameters]

| Parameter | Type                      | Description                                           |
| --------- | ------------------------- | ----------------------------------------------------- |
| `context` | `Record<string, unknown>` | Context data to merge into all crumbs from this child |

Return value [#return-value]

Returns a new trail function with the same API. All crumbs emitted include the merged context.

Nesting children [#nesting-children]

Children can have children. Context merges at each level:

```typescript
const reqCrumb = crumb.child({ requestId: "abc" }); // @crumbs
const dbCrumb = reqCrumb.child({ database: "primary" }); // @crumbs
dbCrumb("running query"); // @crumbs
// ctx: { requestId: "abc", database: "primary" }
```

When disabled [#when-disabled]

`child()` returns the same frozen noop object. No allocation occurs.


# scope() and wrap() (/docs/api/scope)



crumb.scope(name, fn) [#crumbscopename-fn]

Wrap a function with automatic entry/exit/error tracking and timing. Returns whatever the function returns. Works with sync and async functions.

```typescript
// #region @crumbs
const user = await crumb.scope("validate-token", async (ctx) => {
  ctx.crumb("checking jwt", { tokenPrefix: token.slice(0, 8) });
  const result = await verify(token);
  ctx.crumb("token valid", { userId: result.id });
  return result;
});
// #endregion @crumbs
```

Output:

```
auth-service [validate-token] -> enter  +0ms
auth-service   checking jwt             +1ms
auth-service   token valid              +15ms
auth-service [validate-token] <- exit   +16ms  { duration: 16.2 }
```

Parameters [#parameters]

| Parameter | Type         | Description                                                          |
| --------- | ------------ | -------------------------------------------------------------------- |
| `name`    | `string`     | Name for the scope (shown in output)                                 |
| `fn`      | `(ctx) => T` | Function to execute. `ctx` has a `crumb` property for scoped crumbs. |

Error handling [#error-handling]

If the function throws, a `scope:error` crumb is emitted with the error details, then the error is re-thrown.

Nested scopes [#nested-scopes]

Scopes nest. Inner scopes get incremented depth and indentation:

```typescript
// #region @crumbs
crumb.scope("outer", (ctx1) => {
  ctx1.crumb.scope("inner", (ctx2) => {
    ctx2.crumb("deep inside");
  });
});
// #endregion @crumbs
```

crumb.wrap(name, fn) [#crumbwrapname-fn]

Wrap any function with automatic scope tracking. Returns a function with the same signature.

```typescript
const trackedFetch = crumb.wrap("fetch", fetch); // @crumbs
const response = await trackedFetch("https://api.example.com/data"); // @crumbs
// Automatically emits scope:enter, scope:exit (or scope:error)
```

Parameters [#parameters-1]

| Parameter | Type       | Description                          |
| --------- | ---------- | ------------------------------------ |
| `name`    | `string`   | Name for the scope (shown in output) |
| `fn`      | `Function` | The function to wrap                 |

Return value [#return-value]

Returns a function with the same signature as the input. When disabled, returns the original function unwrapped.


# Sessions (/docs/api/sessions)



crumb.session(name) / crumb.session(name, fn) [#crumbsessionname--crumbsessionname-fn]

Group crumbs into logical sessions for later replay and filtering.

Manual session [#manual-session]

```typescript
// #region @crumbs
const session = crumb.session("investigating-timeout");
session.crumb("checking connection pool", { active: 5, idle: 0 });
session.crumb("found stale connection", { age: "45s" }, { tags: ["root-cause"] });
session.end();
// #endregion @crumbs
```

Scoped session (auto-ends) [#scoped-session-auto-ends]

```typescript
// #region @crumbs
await crumb.session("user-signup", async (s) => {
  s.crumb("validating email");
  s.crumb("creating account", { email });
});
// #endregion @crumbs
```

Parameters [#parameters]

**`session(name)`** returns a session object

| Parameter | Type     | Description                              |
| --------- | -------- | ---------------------------------------- |
| `name`    | `string` | Session name (for display and filtering) |

**`session(name, fn)`** scoped session

| Parameter | Type             | Description                            |
| --------- | ---------------- | -------------------------------------- |
| `name`    | `string`         | Session name                           |
| `fn`      | `(session) => T` | Function to execute within the session |

Session object [#session-object]

| Property/Method                       | Description                           |
| ------------------------------------- | ------------------------------------- |
| `session.crumb(msg, data?, options?)` | Drop a crumb tagged with this session |
| `session.end()`                       | End the session                       |

Tags [#tags]

Add tags to any crumb for filtering:

```typescript
crumb("cache miss", { key }, { tags: ["perf", "cache"] }); // @crumbs
```

Tags can be filtered with the CLI:

```bash
agentcrumbs tail --tag perf
agentcrumbs query --since 1h --tag root-cause
```


# Timing and assertions (/docs/api/timing)



crumb.time(label) / crumb.timeEnd(label, data?) [#crumbtimelabel--crumbtimeendlabel-data]

Measure the duration of an operation.

```typescript
crumb.time("db-query"); // @crumbs
const rows = await db.query("SELECT * FROM users");
crumb.timeEnd("db-query", { rowCount: rows.length }); // @crumbs
// Emits: { msg: "db-query", type: "time", data: { rowCount: 42, duration: 12.5 } }
```

Parameters [#parameters]

**`time(label)`**

| Parameter | Type     | Description                                           |
| --------- | -------- | ----------------------------------------------------- |
| `label`   | `string` | Timer label (must match between `time` and `timeEnd`) |

**`timeEnd(label, data?)`**

| Parameter | Type      | Description                                    |
| --------- | --------- | ---------------------------------------------- |
| `label`   | `string`  | Timer label (must match `time`)                |
| `data`    | `unknown` | Optional data to include with the timing crumb |

crumb.snapshot(label, obj) [#crumbsnapshotlabel-obj]

Capture a point-in-time snapshot of an object using `structuredClone`. The snapshot is independent of future mutations to the original object.

```typescript
crumb.snapshot("state-before", complexObject); // @crumbs
mutate(complexObject);
crumb.snapshot("state-after", complexObject); // @crumbs
```

Parameters [#parameters-1]

| Parameter | Type      | Description                                       |
| --------- | --------- | ------------------------------------------------- |
| `label`   | `string`  | Label for the snapshot                            |
| `obj`     | `unknown` | Object to snapshot (cloned via `structuredClone`) |

crumb.assert(condition, msg) [#crumbassertcondition-msg]

Debug-only assertion. Emits a crumb when the condition is falsy. Never throws. This is for debug tracing, not validation.

```typescript
crumb.assert(user != null, "user should exist after auth"); // @crumbs
crumb.assert(items.length > 0, "cart should not be empty"); // @crumbs
```

Parameters [#parameters-2]

| Parameter   | Type      | Description                             |
| ----------- | --------- | --------------------------------------- |
| `condition` | `unknown` | Condition to check                      |
| `msg`       | `string`  | Message emitted when condition is falsy |


# trail() (/docs/api/trail)



trail(namespace) [#trailnamespace]

Create a trail function for a namespace. Returns a frozen noop if the namespace is disabled.

```typescript
import { trail } from "agentcrumbs"; // @crumbs
const crumb = trail("my-service"); // @crumbs
```

The returned `crumb` function is the primary API. Call it to drop a crumb:

```typescript
crumb("user authenticated", { userId: "123", method: "oauth" }); // @crumbs
crumb("cache miss", { key: "users:123" }, { tags: ["perf", "cache"] }); // @crumbs
```

Parameters [#parameters]

| Parameter   | Type     | Description                                               |
| ----------- | -------- | --------------------------------------------------------- |
| `namespace` | `string` | Namespace for this trail. Used for filtering and display. |

Return value [#return-value]

Returns a `TrailFn`, a callable function with additional methods:

| Property/Method                | Description                                 |
| ------------------------------ | ------------------------------------------- |
| `crumb(msg, data?, options?)`  | Drop a crumb (the function itself)          |
| `crumb.enabled`                | `boolean`. Whether this trail is active.    |
| `crumb.scope(name, fn)`        | Wrap a function with enter/exit tracking    |
| `crumb.child(context)`         | Create a child trail with inherited context |
| `crumb.wrap(name, fn)`         | Wrap any function with scope tracking       |
| `crumb.time(label)`            | Start a timer                               |
| `crumb.timeEnd(label, data?)`  | End a timer                                 |
| `crumb.snapshot(label, obj)`   | Capture a point-in-time snapshot            |
| `crumb.assert(condition, msg)` | Debug-only assertion                        |
| `crumb.session(name)`          | Start a session                             |

The noop guarantee [#the-noop-guarantee]

When a namespace is disabled, `trail()` returns a pre-built frozen noop function. There is no `if (enabled)` check on every call. The function itself IS the noop.

```typescript
// When tracing is not enabled:
const crumb = trail("my-service");  // returns frozen NOOP
crumb("msg", { data });              // empty function, returns undefined
crumb.scope("op", fn);               // calls fn() directly
crumb.child({ rid: "x" });           // returns same frozen NOOP
crumb.wrap("fetch", fetch);          // returns the original fetch
```

Best practices [#best-practices]

Create trails at module level, not inside functions:

```typescript
// Good: created once
import { trail } from "agentcrumbs"; // @crumbs
const crumb = trail("api"); // @crumbs

function handleRequest(req: Request) {
  crumb("handling", { path: req.url }); // @crumbs
}
```

```typescript
// Bad: re-created on every call
function handleRequest(req: Request) {
  const crumb = trail("api"); // parses env var every time
  crumb("handling", { path: req.url });
}
```

Guarding expensive arguments [#guarding-expensive-arguments]

The only overhead when disabled is argument evaluation. For hot paths with expensive arguments:

```typescript
// #region @crumbs
if (crumb.enabled) {
  crumb("full dump", { state: structuredClone(everything) });
}
// #endregion @crumbs
```


# collect (/docs/cli/collect)



agentcrumbs collect [#agentcrumbs-collect]

The collector is an HTTP server that receives crumbs via `POST /crumb` and writes them to a JSONL file. Without it running, crumbs fall back to stderr only and can't be queried later.

```bash
agentcrumbs collect
# agentcrumbs collector
#   http:  http://localhost:8374/crumb
#   crumbs stored per-app in ~/.agentcrumbs/<app>/
#   press ctrl+c to stop
```

Agent workflow [#agent-workflow]

When an agent needs to debug something, it should start the collector, clear old crumbs, reproduce, and query:

```bash
agentcrumbs collect --quiet &
agentcrumbs clear
AGENTCRUMBS=1 node app.js
agentcrumbs query
```

Clear before reproducing so you only see crumbs from this run. No `--since` guessing needed. The `--quiet` flag keeps the collector from cluttering stdout.

Options [#options]

| Flag      | Default          | Description                     |
| --------- | ---------------- | ------------------------------- |
| `--port`  | `8374`           | HTTP port                       |
| `--dir`   | `~/.agentcrumbs` | Storage directory               |
| `--quiet` | `false`          | No stdout output, just collects |

Examples [#examples]

```bash
# Custom port and storage
agentcrumbs collect --port 9999 --dir /var/log/crumbs

# Quiet mode
agentcrumbs collect --quiet
```

How it works [#how-it-works]

1. Listens on the specified port for `POST /crumb` requests
2. Validates the JSON body matches the crumb schema
3. Routes each crumb to per-app storage at `~/.agentcrumbs/<app>/crumbs.jsonl`
4. The `tail` and `query` commands read from these files

Without the collector [#without-the-collector]

If the collector isn't running, crumbs still print to stderr (via ConsoleSink). You can read them in the terminal output, but `tail`, `query`, and `replay` won't work because nothing is writing to the JSONL file.

For single-service debugging where you just want to see crumbs in the console, you don't need the collector. For multi-service setups or querying historical crumbs, start it first.


# Other commands (/docs/cli/other)



All commands below accept `--app <name>` to scope to a specific app and `--all-apps` to include all apps. Default is auto-detect from `package.json`.

agentcrumbs stats [#agentcrumbs-stats]

Show crumb counts, file size, and active services.

```bash
agentcrumbs stats              # current app
agentcrumbs stats --all-apps   # per-app breakdown
```

agentcrumbs clear [#agentcrumbs-clear]

Delete stored crumbs.

```bash
agentcrumbs clear              # clear current app
agentcrumbs clear --all-apps   # clear all apps
agentcrumbs clear --app foo    # clear a specific app
```

agentcrumbs sessions [#agentcrumbs-sessions]

List all recorded sessions.

```bash
agentcrumbs sessions
# ID          Name                        Duration  Crumbs  Status
# ----------  -------------------------  ----------  ------  ------
# a1b2c3      debugging-auth-timeout     2m 15s      47     stopped
```

agentcrumbs replay [#agentcrumbs-replay]

Replay a session's crumbs in order.

```bash
agentcrumbs replay a1b2c3
```

agentcrumbs follow [#agentcrumbs-follow]

Follow a specific trace across services.

```bash
agentcrumbs follow --trace a1b2c3
```

agentcrumbs --help [#agentcrumbs---help]

Show full help text.

```bash
agentcrumbs --help
```


# query (/docs/cli/query)



agentcrumbs query [#agentcrumbs-query]

Query historical crumbs with time windows and cursor-based pagination.

```bash
agentcrumbs query --since 5m
```

Options [#options]

| Flag                   | Description                                                      |
| ---------------------- | ---------------------------------------------------------------- |
| `--since <duration>`   | Relative time window (e.g., `5m`, `1h`, `24h`, `7d`)             |
| `--after <timestamp>`  | Crumbs after this ISO timestamp                                  |
| `--before <timestamp>` | Crumbs before this ISO timestamp                                 |
| `--cursor <id>`        | Resume from a previous page (8-char ID from output)              |
| `--limit <n>`          | Results per page (default: 50)                                   |
| `--ns <pattern>`       | Filter by namespace                                              |
| `--tag <tag>`          | Filter by tag                                                    |
| `--session <id>`       | Filter by session ID                                             |
| `--match <text>`       | Text search                                                      |
| `--app <name>`         | Scope to a specific app (default: auto-detect from package.json) |
| `--all-apps`           | Query crumbs from all apps                                       |
| `--json`               | JSON output                                                      |

Time units: `s` (seconds), `m` (minutes), `h` (hours), `d` (days).

Pagination [#pagination]

Results are returned oldest-first, capped at `--limit` (default 50). When there are more results, the output includes a short cursor ID for the next page.

```bash
# First page
agentcrumbs query --since 5m
# Output: 50 crumbs (1-50 of 128). Next: --cursor a1b2c3d4

# Next page
agentcrumbs query --since 5m --cursor a1b2c3d4
# Output: 50 crumbs (51-100 of 128). Next: --cursor e5f6g7h8
```

Cursors expire after 1 hour. You can also use `--after` / `--before` with ISO timestamps for explicit time windows without cursors.

Examples [#examples]

```bash
# Last 5 minutes (all namespaces)
agentcrumbs query --since 5m

# Paginate through results
agentcrumbs query --since 5m --cursor a1b2c3d4

# Time window with absolute timestamps
agentcrumbs query --after 2026-03-11T14:00:00Z --before 2026-03-11T14:05:00Z

# Smaller pages
agentcrumbs query --since 1h --limit 25

# Filter by session
agentcrumbs query --session a1b2c3

# Filter by tag
agentcrumbs query --tag root-cause

# Query a specific app
agentcrumbs query --since 1h --app my-project

# Query across all apps
agentcrumbs query --since 5m --all-apps
```


# session (/docs/cli/session)



agentcrumbs session [#agentcrumbs-session]

Start and stop debug sessions from the CLI. When a session is active, all services automatically tag their crumbs with the session ID.

Start a session [#start-a-session]

```bash
agentcrumbs session start "debugging-auth-timeout"
# Session started: a1b2c3 (debugging-auth-timeout)
# All services will tag crumbs with this session.
```

Stop a session [#stop-a-session]

```bash
agentcrumbs session stop
# Session stopped: a1b2c3 (debugging-auth-timeout) - 2m 15s
```

How it works [#how-it-works]

The session mechanism works by writing the active session ID to `/tmp/agentcrumbs.session`. Library instances check this file and automatically attach the session ID to outgoing crumbs. No code changes needed.

Filtering by session [#filtering-by-session]

```bash
# Tail only session crumbs
agentcrumbs tail --session a1b2c3

# Query session crumbs
agentcrumbs query --session a1b2c3
```


# strip (/docs/cli/strip)



agentcrumbs strip [#agentcrumbs-strip]

Remove all `// @crumbs` lines and `#region @crumbs` blocks from source files. Run this before merging PRs.

```bash
agentcrumbs strip
```

Options [#options]

| Flag                 | Description                                   |
| -------------------- | --------------------------------------------- |
| `--dry-run`          | Preview without modifying files               |
| `--check`            | CI mode. Exits 1 if markers are found.        |
| `--dir <path>`       | Custom directory (default: current directory) |
| `--ext <extensions>` | File extensions to scan (comma-separated)     |

Default scans `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.mts` files. Skips `node_modules`, `dist`, `.git`.

What gets removed [#what-gets-removed]

**Single-line markers**: any line ending with `// @crumbs` or `/* @crumbs */`:

```typescript
import { trail } from "agentcrumbs"; // @crumbs  // ← this entire line
const crumb = trail("my-service"); // @crumbs     // ← this entire line
crumb("checkpoint"); // @crumbs                    // ← this entire line
```

**Block markers**: everything between `#region @crumbs` and `#endregion @crumbs`:

```typescript
// #region @crumbs    // ← removed
const session = crumb.session("debug");
session.crumb("step 1");
session.end();
// #endregion @crumbs  // ← removed (entire block)
```

Examples [#examples]

```bash
# Preview what would be removed
agentcrumbs strip --dry-run

# Remove all crumb markers
agentcrumbs strip

# CI check (fails if markers found)
agentcrumbs strip --check

# Custom scope
agentcrumbs strip --dir src/ --ext ts,tsx,js
```

CI integration [#ci-integration]

Add to your CI pipeline to prevent crumbs from reaching main:

```yaml
# GitHub Actions
- name: Check for crumb markers
  run: npx agentcrumbs strip --check
```


# tail (/docs/cli/tail)



agentcrumbs tail [#agentcrumbs-tail]

Watch crumbs in real time. Reads from the JSONL file and watches for changes.

```bash
agentcrumbs tail
```

Options [#options]

| Flag             | Description                                                      |
| ---------------- | ---------------------------------------------------------------- |
| `--ns <pattern>` | Filter by namespace (supports wildcards)                         |
| `--tag <tag>`    | Filter by tag                                                    |
| `--match <text>` | Filter by content                                                |
| `--session <id>` | Filter by session ID                                             |
| `--app <name>`   | Scope to a specific app (default: auto-detect from package.json) |
| `--all-apps`     | Show crumbs from all apps                                        |
| `--json`         | JSON output (for piping to jq, etc.)                             |

Examples [#examples]

```bash
# Filter by namespace
agentcrumbs tail --ns auth-service
agentcrumbs tail --ns "auth-*"

# Filter by tag
agentcrumbs tail --tag perf

# Filter by content
agentcrumbs tail --match "userId:123"

# Filter by session
agentcrumbs tail --session a1b2c3

# Scope to a specific app
agentcrumbs tail --app my-project

# Show crumbs from all apps
agentcrumbs tail --all-apps

# JSON output for piping
agentcrumbs tail --json | jq '.data.userId'
```


# Environment variable (/docs/config/env-var)



In Node.js, everything is controlled by a single `AGENTCRUMBS` environment variable. In the browser, use [`configure()`](/guides/browser) instead.

Shorthand values [#shorthand-values]

| Value   | Effect                        |
| ------- | ----------------------------- |
| `1`     | Enable all namespaces         |
| `*`     | Enable all namespaces         |
| `true`  | Enable all namespaces         |
| (unset) | Disabled. All calls are noop. |

```bash
AGENTCRUMBS=1 node your-app.js
```

Namespace filter [#namespace-filter]

Non-JSON string values are treated as namespace filters:

```bash
AGENTCRUMBS=auth-*           # Wildcard match
AGENTCRUMBS=auth-service     # Exact match
```

JSON config [#json-config]

For full control, pass a JSON object:

```bash
# Enable specific namespaces
AGENTCRUMBS='{"ns":"auth-*,api-*"}'

# With exclusions
AGENTCRUMBS='{"ns":"* -internal-*"}'

# Custom port
AGENTCRUMBS='{"ns":"*","port":9999}'

# JSON output format (instead of pretty)
AGENTCRUMBS='{"ns":"*","format":"json"}'

# Explicit app name
AGENTCRUMBS='{"app":"my-project","ns":"*"}'
```

Config schema [#config-schema]

| Field    | Type                   | Default       | Description                                       |
| -------- | ---------------------- | ------------- | ------------------------------------------------- |
| `app`    | `string`               | (auto-detect) | App name. Defaults to nearest `package.json` name |
| `ns`     | `string`               | (required)    | Namespace filter pattern                          |
| `port`   | `number`               | `8374`        | Collector HTTP port                               |
| `format` | `"pretty"` \| `"json"` | `"pretty"`    | Output format for stderr                          |

App name [#app-name]

Every crumb is stamped with an app name. This keeps crumbs from different projects separate.

The app name is resolved in this order:

1. `app` field in the JSON config
2. `AGENTCRUMBS_APP` environment variable
3. Auto-detected from the nearest `package.json` name field (walking up from `cwd`)
4. Fallback: `"unknown"`

```bash
# Override via dedicated env var
AGENTCRUMBS_APP=my-project AGENTCRUMBS=1 node app.js
```

Namespace patterns [#namespace-patterns]

* `*` matches everything
* `auth-*` matches `auth-service`, `auth-oauth`, etc.
* `auth-*,api-*` matches multiple patterns (comma or space separated)
* `* -internal-*` matches everything except namespaces starting with `internal-`


# Sinks (/docs/config/sinks)



By default, crumbs are sent via HTTP to the collector and also printed to the console. In Node.js, output goes to stderr with ANSI colors. In the browser, output goes to `console.debug()` with CSS styling. You can add custom sinks or replace the defaults.

Custom sink [#custom-sink]

```typescript
import { trail, addSink, removeSink } from "agentcrumbs";
import type { Sink, Crumb } from "agentcrumbs";

const mySink: Sink = {
  write(crumb: Crumb) {
    myLogger.info(crumb);
  },
};

addSink(mySink);
```

Built-in sinks [#built-in-sinks]

HttpSink [#httpsink]

Sends crumbs to the collector via HTTP. Added automatically when `AGENTCRUMBS` is set.

```typescript
import { HttpSink } from "agentcrumbs";
```

ConsoleSink [#consolesink]

Pretty-printed console output. Added automatically when tracing is enabled.

* **Node.js**: ANSI-colored output to stderr
* **Browser**: CSS-styled output via `console.debug()`, with `console.groupCollapsed()` for scopes and interactive object rendering in DevTools

```typescript
import { ConsoleSink } from "agentcrumbs";
```

Sink interface [#sink-interface]

```typescript
interface Sink {
  write(crumb: Crumb): void;
}
```

The `write` method receives a `Crumb` object (see [crumb format](/crumb-format)). It should not throw.


# Browser (/docs/guides/browser)



agentcrumbs works in the browser with the same `"agentcrumbs"` import. Bundlers that respect the `"browser"` export condition (Vite, webpack, esbuild, Next.js) automatically resolve to the browser build.

Enable tracing [#enable-tracing]

Browsers don't have environment variables. Use `configure()` instead:

```typescript
import { configure, trail } from "agentcrumbs"; // @crumbs

configure("*"); // @crumbs — enable all namespaces

const crumb = trail("ui"); // @crumbs
```

`configure()` accepts the same values as the `AGENTCRUMBS` env var:

```typescript
// Enable all
configure("*"); // @crumbs

// Namespace filter
configure("ui-*,api-*"); // @crumbs

// Full config object
configure({ ns: "ui-*", app: "my-app", format: "pretty" }); // @crumbs
```

Call `configure()` before any `trail()` calls. A good place is your app's entry point.

Declarative fallback [#declarative-fallback]

You can also set config on `globalThis` before importing agentcrumbs:

```html
<script>
  window.__AGENTCRUMBS__ = "*";
  // or: window.__AGENTCRUMBS__ = { ns: "ui-*", app: "my-app" };
  // or set just the app name: window.__AGENTCRUMBS_APP__ = "my-app";
</script>
```

App name [#app-name]

In the browser, the app name is resolved in this order:

1. `app` field from `configure()` config
2. `globalThis.__AGENTCRUMBS_APP__`
3. Fallback: `"browser"`

Console output [#console-output]

In the browser, crumbs are written to `console.debug()` with CSS styling:

* Namespace labels are color-coded
* Scope enter/exit use `console.groupCollapsed()` / `console.groupEnd()` for collapsible nesting
* Data objects are passed as additional arguments so DevTools renders them interactively

When `format: "json"` is set, crumbs are written as JSON strings via `console.debug()`.

Collector support [#collector-support]

The browser build includes the HTTP sink, so crumbs are sent to the collector just like in Node.js. Start `agentcrumbs collect` on your dev machine and crumbs from both your server and browser flow to the same place.

```bash
# Terminal: Start collector
agentcrumbs collect

# Browser crumbs + server crumbs appear together
agentcrumbs tail --all-apps
```

The browser defaults to `http://localhost:8374/crumb`. Make sure CORS allows it, or the HTTP sink silently fails (crumbs still appear in the DevTools console).

Differences from Node.js [#differences-from-nodejs]

|                    | Node.js                          | Browser                      |
| ------------------ | -------------------------------- | ---------------------------- |
| **Config**         | `AGENTCRUMBS` env var            | `configure()` call           |
| **Console output** | ANSI-colored stderr              | CSS-styled DevTools console  |
| **Async context**  | `AsyncLocalStorage`              | Sync stack (single-threaded) |
| **Process ID**     | `process.pid`                    | `0`                          |
| **Session file**   | Reads `/tmp/agentcrumbs.session` | Skipped                      |
| **UUID**           | `node:crypto`                    | Web Crypto API               |
| **App fallback**   | Nearest `package.json` name      | `"browser"`                  |

Context isolation [#context-isolation]

The browser uses a sync stack instead of `AsyncLocalStorage`. This works for all linear async flows. However, concurrent branches in `Promise.all` won't isolate context from each other. This is acceptable for debugging — just be aware that nested scopes inside `Promise.all` may share context.

configure() in Node.js [#configure-in-nodejs]

`configure()` is exported from both builds so your code compiles in both environments. In Node.js it's a no-op — use the `AGENTCRUMBS` env var instead.


# Cross-language support (/docs/guides/cross-language)



The collector and CLI are language-agnostic. Any language with HTTP support can send crumbs.

Protocol [#protocol]

Send a `POST` request to `http://localhost:8374/crumb` with a JSON body matching the [crumb format](/crumb-format).

Required fields [#required-fields]

| Field  | Type     | Description                                 |
| ------ | -------- | ------------------------------------------- |
| `app`  | `string` | App name (used for per-app storage routing) |
| `ts`   | `string` | ISO 8601 timestamp                          |
| `ns`   | `string` | Namespace                                   |
| `msg`  | `string` | Message                                     |
| `type` | `string` | Crumb type (usually `"crumb"`)              |
| `dt`   | `number` | Delta time in ms (use `0` if unknown)       |
| `pid`  | `number` | Process ID                                  |

Optional fields [#optional-fields]

| Field     | Type       | Description        |
| --------- | ---------- | ------------------ |
| `data`    | `unknown`  | Structured data    |
| `ctx`     | `object`   | Context data       |
| `tags`    | `string[]` | Tags for filtering |
| `sid`     | `string`   | Session ID         |
| `traceId` | `string`   | Trace ID           |
| `depth`   | `number`   | Nesting depth      |

Examples [#examples]

curl [#curl]

```bash
curl -X POST http://localhost:8374/crumb \
  -H "Content-Type: application/json" \
  -d '{"app":"my-app","ts":"2026-01-01T00:00:00Z","ns":"shell","msg":"hello","type":"crumb","dt":0,"pid":1}'
```

Python [#python]

```python
import requests, os, json
from datetime import datetime

def crumb(ns, msg, data=None):
    try:
        requests.post("http://localhost:8374/crumb", json={
            "app": "my-app",
            "ts": datetime.utcnow().isoformat() + "Z",
            "ns": ns,
            "msg": msg,
            "type": "crumb",
            "dt": 0,
            "pid": os.getpid(),
            "data": data
        }, timeout=0.1)
    except:
        pass

crumb("python-service", "processing started", {"items": 42})
```

Go [#go]

```go
func crumb(ns, msg string, data any) {
    body, _ := json.Marshal(map[string]any{
        "app":  "my-app",
        "ts":   time.Now().UTC().Format(time.RFC3339Nano),
        "ns":   ns,
        "msg":  msg,
        "type": "crumb",
        "dt":   0,
        "pid":  os.Getpid(),
        "data": data,
    })
    go http.Post("http://localhost:8374/crumb", "application/json", bytes.NewReader(body))
}
```

Rust [#rust]

```rust
fn crumb(ns: &str, msg: &str) {
    let body = serde_json::json!({
        "app": "my-app",
        "ts": chrono::Utc::now().to_rfc3339(),
        "ns": ns,
        "msg": msg,
        "type": "crumb",
        "dt": 0,
        "pid": std::process::id()
    });
    // fire and forget
    tokio::spawn(async move {
        let _ = reqwest::Client::new()
            .post("http://localhost:8374/crumb")
            .json(&body)
            .send()
            .await;
    });
}
```

Session integration [#session-integration]

To integrate with CLI-initiated sessions, read the session ID from `/tmp/agentcrumbs.session` and include it as the `sid` field in your crumbs.

Runtime requirements [#runtime-requirements]

The TypeScript package includes the canonical collector and CLI. Install it globally or use `npx`:

```bash
npm install -g agentcrumbs
# or
npx agentcrumbs collect
```


# Multi-service setup (/docs/guides/multi-service)



agentcrumbs is designed for systems with multiple services running locally.

Architecture [#architecture]

```
Service A ──┐                                ┌── $ agentcrumbs tail
Service B ──┤── fetch() ──> Collector :8374 ──┤── $ agentcrumbs query --since 5m
Service C ──┘  (fire & forget)               └── ~/.agentcrumbs/<app>/crumbs.jsonl
```

1. Each service imports `agentcrumbs` and calls `trail()` to create namespaced trail functions
2. When `AGENTCRUMBS` is set, crumbs are sent via HTTP to the collector
3. The collector routes crumbs to per-app storage at `~/.agentcrumbs/<app>/crumbs.jsonl`
4. The CLI reads from these files to provide tail, query, and replay (auto-scoped to current app)

Setup [#setup]

```bash
# Terminal 1: Start collector
agentcrumbs collect

# Terminal 2: Start your services
AGENTCRUMBS=1 node auth-service.js &
AGENTCRUMBS=1 node api-gateway.js &
AGENTCRUMBS=1 node task-runner.js &

# Terminal 3: Watch everything
agentcrumbs tail

# Or filter to one service
agentcrumbs tail --ns auth-service
```

All services write to the same collector, so `agentcrumbs tail` shows interleaved output from all services with namespace-colored labels.

Per-service filtering [#per-service-filtering]

Use the namespace filter to enable only specific services:

```bash
# Only auth service crumbs
AGENTCRUMBS='auth-service' node auth-service.js

# Auth and API crumbs
AGENTCRUMBS='{"ns":"auth-*,api-*"}' node api-gateway.js

# Everything except internal
AGENTCRUMBS='{"ns":"* -internal-*"}' node task-runner.js
```

Custom collector port [#custom-collector-port]

If port 8374 is taken:

```bash
# Collector on custom port
agentcrumbs collect --port 9999

# Services must match
AGENTCRUMBS='{"ns":"*","port":9999}' node auth-service.js
```


# Tracing into node_modules (/docs/guides/node-modules)



You can add crumbs directly to files inside `node_modules/` to trace into library internals. See what a dependency is actually doing, what it receives, what it returns. These files are gitignored and never committed, so no `// @crumbs` markers are needed.

Raw fetch, no import required [#raw-fetch-no-import-required]

Paste this anywhere in a `node_modules` file:

```javascript
fetch("http://localhost:8374/crumb", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    ts: new Date().toISOString(),
    ns: "library-name",
    msg: "what is happening here",
    type: "crumb",
    dt: 0,
    pid: process.pid,
    data: { arg1, arg2 }
  })
}).catch(() => {});
```

This sends a crumb directly to the collector via HTTP. No import needed. `fetch` is available globally in Node 18+ and Bun.

Why this works [#why-this-works]

* `node_modules/` is gitignored, so changes never get committed
* No `// @crumbs` markers needed since the files aren't tracked
* A fresh `npm install` resets everything back to normal
* The collector receives crumbs from any source. It doesn't care if they come from your code or a library.

Tips [#tips]

* Change `ns` to the library name so crumbs show up with a clear label in `tail`
* Include relevant variables in `data`: function arguments, return values, internal state
* Add `.catch(() => {})` so the crumb never throws if the collector isn't running
* For one-liner insertion: keep it on a single line

```javascript
fetch("http://localhost:8374/crumb", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ ts: new Date().toISOString(), ns: "lib-name", msg: "debug", type: "crumb", dt: 0, pid: process.pid, data: { val } }) }).catch(() => {});
```


# For PR reviewers (/docs/guides/pr-reviewers)



For AI code reviewers [#for-ai-code-reviewers]

If you're an AI reviewing a PR that contains `// @crumbs` markers or `#region @crumbs` blocks: **do not flag these.** They're temporary debug instrumentation that gets stripped before merge.

Do not comment on [#do-not-comment-on]

* `agentcrumbs` imports or trail declarations
* Lines marked with `// @crumbs` or `/* @crumbs */`
* Blocks between `// #region @crumbs` and `// #endregion @crumbs`
* Data logged in crumbs (including IDs, names, or other values; these never reach production)

Why [#why]

These markers are the project's convention for debug tracing during development. They're removed by `agentcrumbs strip` as a pre-merge step. The CI pipeline runs `agentcrumbs strip --check` to ensure no markers reach main.

What to check instead [#what-to-check-instead]

* The actual business logic (non-crumb code)
* Whether the `agentcrumbs strip --check` CI step is present
* That crumb data doesn't include actual secrets (API keys, passwords). Even if it did, it only appears in local debug output.

For human reviewers [#for-human-reviewers]

When reviewing a PR with crumb markers:

1. **Ignore crumb lines.** They'll be stripped before merge.
2. **Check the CI step.** Make sure `agentcrumbs strip --check` is in the pipeline.
3. **Review the actual code.** Focus on the business logic between the crumb markers.