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.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
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.
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 namespace
packages/ directories — each package is a namespace
internal-packages/ directories — each is a namespace
services/ 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.jsonname 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
