For Claude Code, Cursor, Copilot, and any agent

Debug mode for
AI agents

Agents can read your code but they can't see what happened at runtime. agentcrumbs lets them drop structured traces inline while writing code, then query those traces when something breaks. Stripped before merge, zero cost when off.

api-gateway.ts
auth-service.ts
billing.ts
import { trail } from "agentcrumbs"; // @crumbs
const crumb = trail("api-gateway"); // @crumbs

export async function handleCheckout(req: Request) {
  crumb("checkout started", { cartId: req.params.id }); // @crumbs

  const user = await authClient.verify(req.token);
  crumb("user verified", { userId: user.id }); // @crumbs

  const charge = await billingClient.charge(user, req.cart);
  crumb("charge result", { status: charge.status }); // @crumbs

  return { orderId: charge.orderId };
}
import { trail } from "agentcrumbs"; // @crumbs
const crumb = trail("auth-service"); // @crumbs

export async function verify(token: string) {
  crumb("token received", { len: token.length }); // @crumbs

  const decoded = jwt.verify(token, SECRET);
  crumb("token decoded", { userId: decoded.sub }); // @crumbs

  const user = await db.users.findById(decoded.sub);
  crumb("user lookup", { found: !!user, plan: user?.plan }); // @crumbs

  return user;
}
import { trail } from "agentcrumbs"; // @crumbs
const crumb = trail("billing"); // @crumbs

export async function charge(user: User, cart: Cart) {
  crumb("charging", { userId: user.id, total: cart.total }); // @crumbs

  const result = await stripe.charges.create({
    amount: cart.total,
    customer: user.stripeId,
  });
  crumb("stripe response", { status: result.status }); // @crumbs

  return { orderId: result.id, status: result.status };
}
claude code
 checkout returns 500 but only for free-tier users

 I can see crumbs across all three services. Let me
  query the trail to see what's happening.

 Bash(agentcrumbs query --since 5m)
   api-gateway     checkout started  +0ms   { cartId: "c_91" }
    auth-service    token received   +1ms   { len: 182 }
    auth-service    token decoded    +4ms   { userId: "u_8f3k" }
    auth-service    user lookup      +9ms   { found: true, plan: "free" }
    api-gateway     user verified    +10ms  { userId: "u_8f3k" }
    billing         charging         +11ms  { total: 4999 }
    billing         stripe response  +80ms  { status: "failed" }
    api-gateway     charge result    +81ms  { status: "failed" }

 Found it. Auth returns plan: "free" but billing
  charges without checking. Free-tier users have
  no stripeId. Stripe fails on null customer.
  Adding a plan check in billing.charge().
1
$npm install agentcrumbs
2
$npx @tanstack/intent install
3
Tell your agent: "Run the agentcrumbs/init skill"

Agents trace their own code

The agent drops crumbs as it writes each function. If a test fails or an API returns garbage, it queries the trail and sees exactly what ran, with what data.

Strip before merge

Crumbs are development-only. agentcrumbs strip removes all traces before merge. CI gate with --check ensures nothing leaks to main.

Zero overhead when off

No AGENTCRUMBS env var? Every call is a frozen noop. No conditionals, no property lookups. The function body is literally empty.

The agent debugging loop

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

01
Agent writes code + crumbs
As the agent implements a feature, it drops crumbs at every decision point, API call, and branch.
02
Something breaks
A test fails, an API returns wrong data, behavior doesn't match expectations.
03
Agent reads the trail
The agent queries crumbs to see what actually executed, in what order, with what data.
04
Strip before merge
Once the code works, agentcrumbs strip removes all crumbs. Clean diff, clean main.
write
debug
fix
strip
merge

The init skill is the real setup

After installing, tell your agent to run agentcrumbs/init. It scans your repo, discovers your services and modules, and builds a namespace catalog that gets written to your agent config (CLAUDE.md, .cursorrules, etc.).

This is the critical step. Without the catalog, every agent invents its own namespace names: auth, auth-service, authService, authentication, all pointing at the same thing. The catalog locks it down. Every agent, every session, same names.

what init writes to your agent config
## agentcrumbs

### Namespaces

| Namespace        | Description                      | Path              |
| ---              | ---                              | ---               |
| api-gateway    | HTTP API and routing             | apps/gateway      |
| auth-service   | Authentication and token handling | apps/auth         |
| billing        | Stripe integration and charges   | apps/billing      |
| task-runner    | Background job execution         | apps/worker       |

Do not invent new namespaces. Pick from this table or ask first.

agentcrumbs ships 5 skills via @tanstack/intent, covering the full API, CLI, and common mistakes. Skills travel with the package version, so the agent always has docs matching the installed code.

Compatible with Claude Code, Cursor, GitHub Copilot, and any agent that supports the Agent Skills spec.

Works with any agent

Claude Code, Cursor, Copilot, Aider, custom agents. If the agent can write code, it can write crumbs.

Trace into node_modules
Agents can paste raw fetch() calls into library code to trace dependencies. No import needed.
Any language via HTTP
POST to the collector from Python, Go, Rust, or any language. The protocol is just HTTP + JSON.
Multi-service
One collector receives crumbs from every service. Bug in service A caused by service B? It's all in the same trail.
Node 18+ / Bun
Zero dependencies. Works with Node 18+ and Bun out of the box.