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.
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 };
}❯ 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().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.
Crumbs are development-only. agentcrumbs strip removes all traces before merge. CI gate with --check ensures nothing leaks to main.
No AGENTCRUMBS env var? Every call is a frozen noop. No conditionals, no property lookups. The function body is literally empty.
Crumbs live on your feature branch. They never ship to main.
agentcrumbs strip removes all crumbs. Clean diff, clean main.agentcrumbs/initThe init skill scans your repo, discovers services and modules, and writes a namespace table to your agent config (CLAUDE.md, .cursorrules, etc.). Agents use the table to pick consistent namespace names across sessions.
my-project| 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 |
agentcrumbs ships 2 skills via @tanstack/intent: one covering the core workflow, API, and common mistakes, and an init skill that sets up your repo. 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.
Claude Code, Cursor, Copilot, Aider, custom agents. If the agent can write code, it can write crumbs.