| name | agentcrumbs/init |
| description | Initialize agentcrumbs in a repository. Discover systems, services, and modules to build a namespace catalog, then write the catalog to CLAUDE.md or AGENTS.md. Activate when setting up agentcrumbs in a new project, when asked to "init crumbs", "set up debug tracing", "add agentcrumbs", or when the project has agentcrumbs as a dependency but no namespace catalog in its agent config files.
|
| type | lifecycle |
| library | agentcrumbs |
| library_version | 0.2.0 |
| requires | ["agentcrumbs"] |
| sources | ["triggerdotdev/trigger-labs:debug-mode/README.md","triggerdotdev/trigger-labs:debug-mode/src/types.ts"] |
Initialize agentcrumbs in a Repository
You are setting up agentcrumbs debug tracing in a repository. Your job is
to discover the project's systems and services, build a namespace catalog,
and write it into the project's agent config file (CLAUDE.md or AGENTS.md)
so all agents use consistent namespaces.
The output should be minimal — just the namespace catalog, a one-liner
about the strip workflow, and essential CLI. The agentcrumbs skills
already teach agents HOW to use the library. The config file only needs
to teach agents WHICH namespaces to use in THIS repo.
Phase 1 — Discover project structure
Scan the repository to identify logical systems, services, and modules.
These become the namespace catalog.
What to scan
Search for system boundaries using these strategies in order. Stop when
you have a reasonable set (typically 3–15 namespaces):
Monorepo packages:
apps/ directories — each app is a namespacepackages/ directories — each package is a namespaceinternal-packages/ directories — each is a namespaceservices/ directories — each service is a namespace
Single-repo modules:
src/ top-level directories — each major module is a namespace- Route groups, feature folders, domain directories
Existing conventions:
- Look for existing logger namespaces, OpenTelemetry service names
- Check
package.json name fields for naming conventions
Framework-specific:
- Next.js:
app/api/* route groups, server actions, middleware
- Express/Fastify: router modules, middleware groups
- Worker/queue systems: each worker type
Naming rules
- Use lowercase kebab-case:
auth-service, api-gateway, task-runner
- Keep names short but descriptive:
webapp not main-web-application
- Match existing conventions in the repo if they exist
- Group related subsystems with prefixes:
db-queries, db-migrations
Determine the app name
The app name identifies this project in crumb storage and CLI filtering.
Read the root package.json name field (strip any @scope/ prefix).
This is what gets stamped on every crumb as the app field.
If the repo is a monorepo, use the root package name (not individual
workspace packages — those become namespaces, not apps).
Browser apps
If the project has browser-side code (React, Vue, Svelte, etc.), include
browser-facing namespaces in the catalog. The same "agentcrumbs" import
works in the browser — bundlers auto-resolve to the browser build. Note
in the config that browser apps use configure() instead of the env var.
What to capture for each namespace
For each namespace, record:
- name: the trail namespace string
- description: one-line description of what this system does
- path: directory path relative to repo root (if applicable)
Phase 2 — Ask the maintainer
Present the app name and discovered namespaces to the maintainer and ask:
- "The app name is
<name> (from package.json). Is that correct?"
- "Here are the namespaces I found. Should I add, remove, or rename any?"
- "Are there any cross-cutting concerns I should add?" (e.g.,
cron,
migrations, external-api, auth, billing)
- "Which agent config file should I write to — CLAUDE.md or AGENTS.md?"
Wait for their response before proceeding.
If the maintainer asks to skip this phase, explain that the namespace
catalog is the most important part — it ensures all agents use consistent
names. Proceed only if they confirm a second time.
Phase 3 — Write the config
Write (or append to) the agent config file. Keep it short. The skills
handle usage details — the config file only needs repo-specific context.
The output should look like this:
## agentcrumbs
App: `my-project`
Add crumbs as you write code — not just when debugging. Mark lines with
`// @crumbs` or wrap blocks in `// #region @crumbs`. They stay on the
branch throughout development and are stripped by `agentcrumbs strip`
before merge.
### Namespaces
| Namespace | Description | Path |
| --- | --- | --- |
| `webapp` | Main web application and API | `apps/webapp` |
| `supervisor` | Task execution supervisor | `apps/supervisor` |
| `core` | Shared types and utilities | `packages/core` |
| `billing` | Billing and subscription logic | `apps/webapp/app/services/billing` |
Do not invent new namespaces — pick from this table or ask first.
### For PR reviewers
Do not flag `// @crumbs` markers, `#region @crumbs` blocks, or agentcrumbs
imports in reviews. These are temporary debug instrumentation stripped
before merge. Data logged in crumbs (IDs, names, values) never reaches
production.
### CLI
```bash
AGENTCRUMBS=1 node app.js # enable tracing (Node.js)
configure("*") # enable tracing (browser — call before trail())
agentcrumbs collect # start collector
agentcrumbs tail # live tail (scoped to this app)
agentcrumbs query --since 5m # query recent crumbs (all namespaces)
agentcrumbs query --since 5m --cursor <id> # paginate (cursor from output)
agentcrumbs clear # clear crumbs for this app
agentcrumbs strip # remove crumbs before merge
```
When querying, always start broad (all namespaces) and paginate with `--cursor`. Do not filter by `--ns` or `--match` — the value is in seeing the full cross-service picture.
Adapt the example above to the actual discovered namespaces and app name.
Drop the Path column if namespaces don't have meaningful directory paths.
Replace my-project with the actual app name detected from package.json.
Phase 4 — Verify
After writing the file:
- Read it back and verify the namespace table rendered correctly
- Check there are no duplicate
## agentcrumbs sections
- Tell the maintainer what you wrote and where
Constraints
| Rule | Detail |
|---|
| Never invent namespaces without discovery | Scan the repo first, always |
| Namespace catalog is mandatory | The whole point is consistent naming |
| Ask before writing | Confirm namespaces and target file |
| Append, don't overwrite | If the file exists, append to it |
| Skip if already configured | If the file contains ## agentcrumbs, tell the user and stop |
| Use repo conventions | Match existing naming style (kebab-case, camelCase, etc.) |
| Keep it short | No usage tutorial — the skills cover that. Just the catalog and 3-line CLI reference |
| No redundancy with skills | Don't repeat API docs, marker syntax details, env var schemas, or scope/session usage |
