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 };
+}` }} />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.
+❯ 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().` }} />npm install agentcrumbs
+
+ npx @tanstack/intent install
+
+ 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. },
+ ].map((step) => (
+ 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.
+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 };
-}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 };
-}❯ 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, testing, 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.
- -