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.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.
## 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.
Claude Code, Cursor, Copilot, Aider, custom agents. If the agent can write code, it can write crumbs.