Quickstart

Install

npm install agentcrumbs

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 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 for details.

Manual setup

If you'd rather set things up by hand:

Add crumbs to your code

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

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

Set the AGENTCRUMBS environment variable:

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

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

# 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)

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

# 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

Crumbs are development-only. Remove them before merging:

# 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

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

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 for details.

Next steps

• Skills: how agents learn to use agentcrumbs from the package itself
• Workflow: how crumbs fit into the branch lifecycle
• API reference: full API docs
• CLI reference: collector, tail, query, strip
• Browser guide: using agentcrumbs in browser apps