{"_id":"agentcrumbs","_rev":"6-8448dbafe062887772f4d61fa62ea382","name":"agentcrumbs","dist-tags":{"latest":"0.5.0"},"versions":{"0.2.0":{"name":"agentcrumbs","version":"0.2.0","keywords":["debug","tracing","agents","ai","logging","observability","claude","cursor","copilot"],"license":"MIT","_id":"agentcrumbs@0.2.0","maintainers":[{"name":"ericallam","email":"eallam@icloud.com"}],"homepage":"https://agentcrumbs.dev","bugs":{"url":"https://github.com/triggerdotdev/agentcrumbs/issues"},"bin":{"intent":"bin/intent.js","agentcrumbs":"dist/cli/index.js"},"dist":{"shasum":"f67e5a32f6f24346e8a2cdfa284a834d5882ebdb","tarball":"https://registry.npmjs.org/agentcrumbs/-/agentcrumbs-0.2.0.tgz","fileCount":114,"integrity":"sha512-ERZRCjdJnReapf6tnc624LWrbdErfDJLly4M45/IeBBtp11B158+Zb9iv3mgJmkBodkBs88RPfR46fmfZ5OqYQ==","signatures":[{"sig":"MEYCIQCEilUv74yvvzdukr3iXM4JcZMeCeKXG3rUM3wQTLRW3QIhAJTFIjfaz6VMrr2LYKBMGS7o/Ilwh0Rp/Wcrwb2hsg9c","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/agentcrumbs@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":168397},"main":"./dist/index.js","type":"module","_from":"file:agentcrumbs-0.2.0.tgz","types":"./dist/index.d.ts","intent":{"docs":"https://docs.agentcrumbs.dev","repo":"triggerdotdev/agentcrumbs","version":1},"engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./test":{"types":"./dist/sinks/memory.d.ts","import":"./dist/sinks/memory.js"}},"scripts":{"dev":"tsc --watch","test":"vitest","build":"tsc","typecheck":"tsc --noEmit"},"_npmUser":{"name":"ericallam","email":"eallam@icloud.com"},"_resolved":"/tmp/3481fea054c3a0a8a54ee8f8649527b6/agentcrumbs-0.2.0.tgz","_integrity":"sha512-ERZRCjdJnReapf6tnc624LWrbdErfDJLly4M45/IeBBtp11B158+Zb9iv3mgJmkBodkBs88RPfR46fmfZ5OqYQ==","repository":{"url":"git+https://github.com/triggerdotdev/agentcrumbs.git","type":"git","directory":"packages/agentcrumbs"},"_npmVersion":"11.6.4","description":"Debug tracing for agents. Drop crumbs, follow the trail.","directories":{},"_nodeVersion":"22.22.0","_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^25.3.3"},"_npmOperationalInternal":{"tmp":"tmp/agentcrumbs_0.2.0_1773137786990_0.09441752310689133","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"agentcrumbs","version":"0.3.0","keywords":["debug","tracing","agents","ai","logging","observability","claude","cursor","copilot"],"license":"MIT","_id":"agentcrumbs@0.3.0","maintainers":[{"name":"ericallam","email":"eallam@icloud.com"}],"homepage":"https://agentcrumbs.dev","bugs":{"url":"https://github.com/triggerdotdev/agentcrumbs/issues"},"bin":{"intent":"bin/intent.js","agentcrumbs":"dist/cli/index.js"},"dist":{"shasum":"36e23d1b4bf40d3fcbd0e587e40e0c5e1c0eaca6","tarball":"https://registry.npmjs.org/agentcrumbs/-/agentcrumbs-0.3.0.tgz","fileCount":110,"integrity":"sha512-WbZ4JhwcQjzBr1rUSeIXUVrKeDwQiAKzGGkpfb9Nl4cDJ34VO3Rx2k5Ej8/om2yaDi7TDLfxHIO4hQvjdHUPSQ==","signatures":[{"sig":"MEYCIQDzOD2coRq2aTF8E1UvcYxnxeN03n4OXXJXbPWj0N5PbgIhAM4DTgYWhVkdvX8GTg1UVg9EqJWjaMsuCQF9rwM6nv9b","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/agentcrumbs@0.3.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":143061},"main":"./dist/index.js","type":"module","_from":"file:agentcrumbs-0.3.0.tgz","types":"./dist/index.d.ts","intent":{"docs":"https://docs.agentcrumbs.dev","repo":"triggerdotdev/agentcrumbs","version":1},"engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./test":{"types":"./dist/sinks/memory.d.ts","import":"./dist/sinks/memory.js"}},"scripts":{"dev":"tsc --watch","test":"vitest","build":"tsc","typecheck":"tsc --noEmit"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:cfd0b1a5-e2e3-4231-ac41-aef74a7b4f17"}},"_resolved":"/tmp/60b1c99d03bbf353bbc33382f7e37369/agentcrumbs-0.3.0.tgz","_integrity":"sha512-WbZ4JhwcQjzBr1rUSeIXUVrKeDwQiAKzGGkpfb9Nl4cDJ34VO3Rx2k5Ej8/om2yaDi7TDLfxHIO4hQvjdHUPSQ==","repository":{"url":"git+https://github.com/triggerdotdev/agentcrumbs.git","type":"git","directory":"packages/agentcrumbs"},"_npmVersion":"11.6.4","description":"Debug mode for any agent.","directories":{},"_nodeVersion":"22.22.0","_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^25.3.3"},"_npmOperationalInternal":{"tmp":"tmp/agentcrumbs_0.3.0_1773151858523_0.7961691173472909","host":"s3://npm-registry-packages-npm-production"}},"0.3.1":{"name":"agentcrumbs","version":"0.3.1","keywords":["debug","tracing","agents","ai","logging","observability","claude","cursor","copilot"],"license":"MIT","_id":"agentcrumbs@0.3.1","maintainers":[{"name":"ericallam","email":"eallam@icloud.com"}],"homepage":"https://agentcrumbs.dev","bugs":{"url":"https://github.com/triggerdotdev/agentcrumbs/issues"},"bin":{"intent":"bin/intent.js","agentcrumbs":"dist/cli/index.js"},"dist":{"shasum":"337ad77f109dea060d650509f286100cf049ee6f","tarball":"https://registry.npmjs.org/agentcrumbs/-/agentcrumbs-0.3.1.tgz","fileCount":110,"integrity":"sha512-65nPVTpRmM8zJ/jmW7i5m+QXyIR3gM2hCUQO5IvWf7wuY4YANAWcSAcTm7kxZiumcGhdC6Ac2RTq7OdbhUMwgQ==","signatures":[{"sig":"MEUCIC+P7UJ7mMtlGuLg0OuhzjbDmUpRu4heMTlUtX13Q/kkAiEA7t7urb3mdbXCOhlU1IYWQY95e6cKlt6bed6iKjIIvuE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/agentcrumbs@0.3.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":142769},"main":"./dist/index.js","type":"module","_from":"file:agentcrumbs-0.3.1.tgz","types":"./dist/index.d.ts","intent":{"docs":"https://agentcrumbs.dev/docs","repo":"triggerdotdev/agentcrumbs","version":1},"engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./test":{"types":"./dist/sinks/memory.d.ts","import":"./dist/sinks/memory.js"}},"scripts":{"dev":"tsc --watch","test":"vitest","build":"tsc","typecheck":"tsc --noEmit"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:cfd0b1a5-e2e3-4231-ac41-aef74a7b4f17"}},"_resolved":"/tmp/68beb7b4e5e85a95db07eb373205bd39/agentcrumbs-0.3.1.tgz","_integrity":"sha512-65nPVTpRmM8zJ/jmW7i5m+QXyIR3gM2hCUQO5IvWf7wuY4YANAWcSAcTm7kxZiumcGhdC6Ac2RTq7OdbhUMwgQ==","repository":{"url":"git+https://github.com/triggerdotdev/agentcrumbs.git","type":"git","directory":"packages/agentcrumbs"},"_npmVersion":"11.6.4","description":"Debug mode for any agent.","directories":{},"_nodeVersion":"22.22.0","_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^25.3.3"},"_npmOperationalInternal":{"tmp":"tmp/agentcrumbs_0.3.1_1773155753834_0.014797560104895968","host":"s3://npm-registry-packages-npm-production"}},"0.3.3":{"name":"agentcrumbs","version":"0.3.3","keywords":["debug","tracing","agents","ai","logging","observability","claude","cursor","copilot"],"license":"MIT","_id":"agentcrumbs@0.3.3","maintainers":[{"name":"ericallam","email":"eallam@icloud.com"}],"homepage":"https://agentcrumbs.dev","bugs":{"url":"https://github.com/triggerdotdev/agentcrumbs/issues"},"bin":{"intent":"bin/intent.js","agentcrumbs":"dist/esm/cli/index.js"},"dist":{"shasum":"b13fa8869f9a793bbf30c31abb59e6f619a41336","tarball":"https://registry.npmjs.org/agentcrumbs/-/agentcrumbs-0.3.3.tgz","fileCount":216,"integrity":"sha512-aupvMKUu/b+7x1scuPVN6Pi5qBXCDpbvCVLrkhpSbvT28ZRaX/ZkZ+LD/96Jg0KP4qCnU8ZOwvGVDUkmSsj+ag==","signatures":[{"sig":"MEYCIQCOXDxy1qc6aI0eitK04+7Y4MVXa5ka6r83sF02iCnHWgIhAJM08gbSyHq4Xs2XYlnM13XnReDpMs/DHX7q3+HI6Urz","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/agentcrumbs@0.3.3","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":273467},"main":"./dist/commonjs/index.js","tshy":{"exclude":["src/__tests__/**/*"],"exports":{".":"./src/index.ts"}},"type":"module","_from":"file:agentcrumbs-0.3.3.tgz","types":"./dist/commonjs/index.d.ts","intent":{"docs":"https://agentcrumbs.dev/docs","repo":"triggerdotdev/agentcrumbs","version":1},"module":"./dist/esm/index.js","engines":{"node":">=18.0.0"},"exports":{".":{"import":{"types":"./dist/esm/index.d.ts","default":"./dist/esm/index.js"},"require":{"types":"./dist/commonjs/index.d.ts","default":"./dist/commonjs/index.js"}}},"scripts":{"dev":"tshy --watch","test":"vitest","build":"tshy","typecheck":"tsc --noEmit"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:cfd0b1a5-e2e3-4231-ac41-aef74a7b4f17"}},"_resolved":"/tmp/1ed5992cc3105606b638a6d881325a5d/agentcrumbs-0.3.3.tgz","_integrity":"sha512-aupvMKUu/b+7x1scuPVN6Pi5qBXCDpbvCVLrkhpSbvT28ZRaX/ZkZ+LD/96Jg0KP4qCnU8ZOwvGVDUkmSsj+ag==","repository":{"url":"git+https://github.com/triggerdotdev/agentcrumbs.git","type":"git","directory":"packages/agentcrumbs"},"_npmVersion":"11.6.4","description":"Debug mode for any agent.","directories":{},"_nodeVersion":"22.22.0","_hasShrinkwrap":false,"devDependencies":{"tshy":"^3.3.2","vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^25.3.3"},"_npmOperationalInternal":{"tmp":"tmp/agentcrumbs_0.3.3_1773221589391_0.667318752981743","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"agentcrumbs","version":"0.4.0","keywords":["debug","tracing","agents","ai","logging","observability","claude","cursor","copilot"],"license":"MIT","_id":"agentcrumbs@0.4.0","maintainers":[{"name":"ericallam","email":"eallam@icloud.com"}],"homepage":"https://agentcrumbs.dev","bugs":{"url":"https://github.com/triggerdotdev/agentcrumbs/issues"},"bin":{"intent":"bin/intent.js","agentcrumbs":"dist/esm/cli/index.js"},"dist":{"shasum":"9eee4bdd99a027a401264362c9e180799b7a894f","tarball":"https://registry.npmjs.org/agentcrumbs/-/agentcrumbs-0.4.0.tgz","fileCount":232,"integrity":"sha512-zQW8wkX1c5M1kSyNMd9KXwOtOHrbGSl9pZZOmDf1lSdQop/l5QJP3OQ43GS3nSRvVMCbjl3T/nPDL5t0PEuyRA==","signatures":[{"sig":"MEYCIQCtd69W8lFhJyOPC0s89WWyZx033jNijzNjmFjmtAakWAIhALkBUK52AHP0hBoR+luJ/OQx3rh0qLJI21FYhyhBg/Ww","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/agentcrumbs@0.4.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":329423},"main":"./dist/commonjs/index.js","tshy":{"exclude":["src/__tests__/**/*"],"exports":{".":"./src/index.ts"}},"type":"module","_from":"file:agentcrumbs-0.4.0.tgz","types":"./dist/commonjs/index.d.ts","intent":{"docs":"https://agentcrumbs.dev/docs","repo":"triggerdotdev/agentcrumbs","version":1},"module":"./dist/esm/index.js","engines":{"node":">=18.0.0"},"exports":{".":{"import":{"types":"./dist/esm/index.d.ts","default":"./dist/esm/index.js"},"require":{"types":"./dist/commonjs/index.d.ts","default":"./dist/commonjs/index.js"}}},"scripts":{"dev":"tshy --watch","test":"vitest","build":"tshy","typecheck":"tsc --noEmit"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:cfd0b1a5-e2e3-4231-ac41-aef74a7b4f17"}},"_resolved":"/tmp/666749667de9c038fa9d36a4818f49bf/agentcrumbs-0.4.0.tgz","_integrity":"sha512-zQW8wkX1c5M1kSyNMd9KXwOtOHrbGSl9pZZOmDf1lSdQop/l5QJP3OQ43GS3nSRvVMCbjl3T/nPDL5t0PEuyRA==","repository":{"url":"git+https://github.com/triggerdotdev/agentcrumbs.git","type":"git","directory":"packages/agentcrumbs"},"_npmVersion":"11.6.4","description":"Debug mode for any agent.","directories":{},"_nodeVersion":"22.22.0","_hasShrinkwrap":false,"devDependencies":{"tshy":"^3.3.2","vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^25.3.3"},"_npmOperationalInternal":{"tmp":"tmp/agentcrumbs_0.4.0_1773245203160_0.17594339550345106","host":"s3://npm-registry-packages-npm-production"}},"0.5.0":{"name":"agentcrumbs","version":"0.5.0","description":"Debug mode for any agent.","tshy":{"exports":{".":"./src/index.ts"},"esmDialects":["browser"],"exclude":["src/__tests__/**/*"]},"bin":{"agentcrumbs":"dist/esm/cli/index.js","intent":"bin/intent.js"},"repository":{"type":"git","url":"git+https://github.com/triggerdotdev/agentcrumbs.git","directory":"packages/agentcrumbs"},"homepage":"https://agentcrumbs.dev","bugs":{"url":"https://github.com/triggerdotdev/agentcrumbs/issues"},"intent":{"version":1,"repo":"triggerdotdev/agentcrumbs","docs":"https://agentcrumbs.dev/docs"},"devDependencies":{"@types/node":"^25.3.3","tshy":"^3.3.2","typescript":"^5.7.0","vitest":"^3.0.0"},"engines":{"node":">=18.0.0"},"license":"MIT","keywords":["debug","tracing","agents","ai","logging","observability","claude","cursor","copilot"],"type":"module","exports":{".":{"browser":{"types":"./dist/browser/index.d.ts","default":"./dist/browser/index.js"},"import":{"types":"./dist/esm/index.d.ts","default":"./dist/esm/index.js"},"require":{"types":"./dist/commonjs/index.d.ts","default":"./dist/commonjs/index.js"}}},"main":"./dist/commonjs/index.js","types":"./dist/commonjs/index.d.ts","module":"./dist/esm/index.js","scripts":{"build":"tshy","dev":"tshy --watch","test":"vitest","typecheck":"tsc --noEmit"},"_id":"agentcrumbs@0.5.0","_integrity":"sha512-+1J7w+x9/DP8oF+ZMVkeXilkd81ydygENEVwLJKwhA3uGQ947DFRwld9hGqAocOcuU4DaQKIdxTzKCsFhpV1Eg==","_resolved":"/tmp/998920ad13c3497b2732226b1b9197f2/agentcrumbs-0.5.0.tgz","_from":"file:agentcrumbs-0.5.0.tgz","_nodeVersion":"22.22.0","_npmVersion":"11.6.4","dist":{"integrity":"sha512-+1J7w+x9/DP8oF+ZMVkeXilkd81ydygENEVwLJKwhA3uGQ947DFRwld9hGqAocOcuU4DaQKIdxTzKCsFhpV1Eg==","shasum":"5c33dbb65fcb6fff40c7134a6178ee6182d11cce","tarball":"https://registry.npmjs.org/agentcrumbs/-/agentcrumbs-0.5.0.tgz","fileCount":345,"unpackedSize":482553,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/agentcrumbs@0.5.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHQYiI0j5OGetS6Mg1AF83ZxxiOtN1h4SuC7sZ5TESZ+AiBkJF+Jmvbr8VwLOH6isKS0B7m3w/a6R8Lq+wYaC3GgoA=="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:cfd0b1a5-e2e3-4231-ac41-aef74a7b4f17"}},"directories":{},"maintainers":[{"name":"ericallam","email":"eallam@icloud.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agentcrumbs_0.5.0_1773333678277_0.891136937624035"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-10T10:16:26.871Z","modified":"2026-03-12T16:41:18.720Z","0.2.0":"2026-03-10T10:16:27.140Z","0.3.0":"2026-03-10T14:10:58.711Z","0.3.1":"2026-03-10T15:15:54.129Z","0.3.3":"2026-03-11T09:33:09.532Z","0.4.0":"2026-03-11T16:06:43.341Z","0.5.0":"2026-03-12T16:41:18.422Z"},"bugs":{"url":"https://github.com/triggerdotdev/agentcrumbs/issues"},"license":"MIT","homepage":"https://agentcrumbs.dev","keywords":["debug","tracing","agents","ai","logging","observability","claude","cursor","copilot"],"repository":{"type":"git","url":"git+https://github.com/triggerdotdev/agentcrumbs.git","directory":"packages/agentcrumbs"},"description":"Debug mode for any agent.","maintainers":[{"name":"ericallam","email":"eallam@icloud.com"}],"readme":"# agentcrumbs\n\nAI agents can read your code but they can't see what happened at runtime. agentcrumbs fixes that. Agents drop structured traces inline as they write code. When something breaks, the agent queries those traces and sees exactly what ran, with what data, in what order.\n\nCrumbs are development-only. They get stripped before merge and cost nothing when disabled.\n\n```\nService A ──┐                                ┌── $ agentcrumbs tail\nService B ──┤── fetch() ──> Collector :8374 ──┤── $ agentcrumbs query --since 5m\nService C ──┘  (fire & forget)               └── ~/.agentcrumbs/<app>/crumbs.jsonl\n```\n\n## Getting started\n\n```bash\nnpm install agentcrumbs\n```\n\nThen tell your agent: **\"Run `npx @tanstack/intent@latest install` to set up agentcrumbs skills, then run the agentcrumbs/init skill.\"**\n\nThe agent will wire the skills into your agent config (CLAUDE.md, .cursorrules, etc.), then scan your repo to build a namespace catalog so all agents use consistent names.\n\n## Agent skills\n\nagentcrumbs ships with [@tanstack/intent](https://tanstack.com/blog/from-docs-to-agents) skills inside the npm package. When your agent runs `npx @tanstack/intent install`, it sets up skill-to-task mappings in your agent config so it knows when to load agentcrumbs patterns.\n\n| Skill | What it teaches |\n| --- | --- |\n| `agentcrumbs` | Core workflow, API, markers, CLI reference, common mistakes |\n| `agentcrumbs/init` | Scans repo, discovers namespaces, writes config |\n\nSkills travel with the package version. The agent always has docs matching the installed code.\n\n## How it works\n\nThe agent writes crumbs as part of the code it's implementing:\n\n```typescript\nimport { trail } from \"agentcrumbs\"; // @crumbs\nconst crumb = trail(\"auth-service\"); // @crumbs\n\nexport async function handleLogin(token: string) {\n  crumb(\"login attempt\", { tokenPrefix: token.slice(0, 8) }); // @crumbs\n\n  const user = await validateToken(token);\n\n  crumb(\"login success\", { userId: user.id }); // @crumbs\n  return user;\n}\n```\n\nWhen something goes wrong, the agent starts the collector and queries the trail:\n\n```bash\nagentcrumbs collect --quiet &\nAGENTCRUMBS=1 node app.js\nagentcrumbs query --since 5m\n```\n\n```\nauth-service  login attempt       +0ms  { tokenPrefix: \"eyJhbGci\" }\nauth-service  token decode ok     +3ms  { userId: \"u_8f3k\" }\nauth-service  permissions check   +8ms  { roles: [] }\nauth-service  rejected: no roles  +8ms  { status: 401 }\n\n4 crumbs.\n```\n\nNow the agent knows: the token is valid, but the user has no roles. The fix is in role assignment, not token validation.\n\n## Workflow\n\nCrumbs live on your feature branch. They never ship to main.\n\n1. **Agent writes code with crumbs.** As it implements a feature, it drops crumbs at every decision point.\n2. **Something breaks.** The agent starts the collector, re-runs the failing code with `AGENTCRUMBS=1`, and queries the trail.\n3. **Agent reads the trail.** It sees what actually executed, in what order, with what data. Fixes the root cause instead of guessing.\n4. **Strip before merge.** `agentcrumbs strip` removes all crumb code. Clean diff, clean main.\n5. **CI enforces it.** `agentcrumbs strip --check` exits 1 if any `@crumbs` markers are found.\n\n## The noop guarantee\n\nWhen a namespace is disabled, `trail()` returns a pre-built frozen noop function. There is no `if (enabled)` check on every call. The function itself is the noop.\n\nThe only cost is the function call itself, which V8 will likely inline after warmup. For hot paths with expensive arguments, gate on `crumb.enabled`.\n\n## API overview\n\nAll methods are documented in detail at [agentcrumbs.dev/docs/api](https://agentcrumbs.dev/docs/api).\n\n| Method | Purpose |\n| --- | --- |\n| `configure(config)` | Enable tracing in the browser (no-op in Node.js) |\n| `trail(namespace)` | Create a trail function for a namespace |\n| `crumb(msg, data?, options?)` | Drop a crumb with message and optional data |\n| `crumb.scope(name, fn)` | Wrap a function with entry/exit/error tracking |\n| `crumb.child(context)` | Create a child trail with inherited context |\n| `crumb.wrap(name, fn)` | Wrap any function with automatic scope tracking |\n| `crumb.time(label)` / `crumb.timeEnd(label)` | Measure operation duration |\n| `crumb.snapshot(label, obj)` | Capture a point-in-time deep clone |\n| `crumb.assert(condition, msg)` | Debug-only assertion (emits crumb, never throws) |\n| `crumb.session(name)` | Group crumbs into logical sessions |\n\n## Crumb markers\n\nMark crumb lines with `// @crumbs` (single line) or `// #region @crumbs` / `// #endregion @crumbs` (block) so they can be stripped before merge. See the [markers docs](https://agentcrumbs.dev/docs/markers) for details and examples.\n\n## Configuration\n\nIn Node.js, everything is controlled by a single `AGENTCRUMBS` environment variable. In the browser, use `configure()`:\n\n```typescript\nimport { configure } from \"agentcrumbs\"; // @crumbs\nconfigure(\"*\"); // @crumbs — enable all namespaces\n```\n\n### Environment variable (Node.js)\n\n| Value | Effect |\n| --- | --- |\n| `1`, `*`, `true` | Enable all namespaces |\n| `auth-service` | Exact namespace match |\n| `auth-*` | Wildcard match |\n| `auth-*,api-*` | Multiple patterns (comma or space separated) |\n| `* -internal-*` | Match all except excluded patterns |\n| `{\"ns\":\"*\",\"port\":9999}` | JSON config with full control |\n| `{\"app\":\"my-app\",\"ns\":\"*\"}` | Explicit app name |\n\nJSON config fields: `app` (app name, default auto-detect from package.json), `ns` (namespace filter, required), `port` (collector port, default 8374), `format` (`\"pretty\"` or `\"json\"`, default `\"pretty\"`).\n\nYou can also set `AGENTCRUMBS_APP` to override the app name independently.\n\n## CLI\n\nCommon commands for reference. Run `agentcrumbs --help` for the full list.\n\n```bash\n# Collector\nagentcrumbs collect --quiet &        # Start in background\nagentcrumbs collect --port 9999      # Custom port\n\n# Live tail\nagentcrumbs tail                     # All namespaces (scoped to current app)\nagentcrumbs tail --ns auth-service   # Filter by namespace\nagentcrumbs tail --app my-app        # Tail a specific app\nagentcrumbs tail --all-apps          # Tail all apps\n\n# Query (paginated, 50 per page)\nagentcrumbs query --since 5m         # Last 5 minutes\nagentcrumbs query --since 5m --cursor a1b2c3d4  # Next page\nagentcrumbs query --since 1h --limit 25          # Smaller pages\nagentcrumbs query --session a1b2c3   # Filter by session\nagentcrumbs query --tag root-cause   # Filter by tag\n\n# Strip\nagentcrumbs strip --dry-run          # Preview removals\nagentcrumbs strip                    # Remove all crumb code\nagentcrumbs strip --check            # CI gate (exits 1 if markers found)\n\n# Utilities\nagentcrumbs stats                    # Crumb counts (current app)\nagentcrumbs stats --all-apps         # Stats for all apps\nagentcrumbs clear                    # Clear crumbs (current app)\n```\n\nTime units: `s` (seconds), `m` (minutes), `h` (hours), `d` (days).\n\n## Multi-service architecture\n\nAll services write to the same collector. `agentcrumbs tail` shows interleaved output with namespace-colored labels. See the [multi-service docs](https://agentcrumbs.dev/docs/multi-service) for setup patterns.\n\n## Cross-language compatibility\n\nThe collector is language-agnostic. Any language with HTTP support can send crumbs:\n\n```bash\ncurl -X POST http://localhost:8374/crumb \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"app\":\"my-app\",\"ts\":\"2026-01-01T00:00:00Z\",\"ns\":\"shell\",\"msg\":\"hello\",\"type\":\"crumb\",\"dt\":0,\"pid\":1}'\n```\n\n## Runtime compatibility\n\nZero runtime dependencies.\n\n- **Node.js 18+** and **Bun** — uses `node:async_hooks`, `node:crypto`, `node:fs`, `node:util`\n- **Browsers** — Vite, webpack, esbuild, Next.js auto-resolve to the browser build via the `\"browser\"` export condition. Same `\"agentcrumbs\"` import path. Use `configure()` instead of the env var to enable tracing. See the [browser guide](https://agentcrumbs.dev/docs/guides/browser).\n\n## Docs\n\nFull documentation at [agentcrumbs.dev/docs](https://agentcrumbs.dev/docs).\n\n## License\n\nMIT\n","readmeFilename":"README.md"}