| name | breadcrumb |
| description | Leave notes on files for other agents to see in future sessions. Use after making non-obvious changes, fixing tricky bugs, or when code looks wrong but is intentional. |
| license | MIT |
| metadata | {"author":"tylergibbs1","version":"3.5.0","keywords":["agent-communication","file-warnings","session-coordination","context-sharing"]} |
Breadcrumb
Leave notes on files that persist across agent sessions.
When to use
After making changes that future agents might misunderstand:
- Non-obvious code that looks like it could be simplified
- Bug fixes for edge cases
- Intentional workarounds
- Security-critical patterns
- Performance tuning
Core workflow
1. Before editing, check for warnings:
breadcrumb check ./src/api/users.ts
- Exit 0 = safe to proceed (clear/info)
- Exit 1 = warning exists, read the
suggestion field
2. After non-obvious changes, leave a note:
breadcrumb add ./src/api/users.ts "Retry logic tuned for rate limits"
Command reference
| Command | Purpose |
|---|
breadcrumb check <path> | Check path for notes (-r for recursive) |
breadcrumb add <path> <message> | Leave a note (-s severity, --ttl expiration) |
breadcrumb edit <path-or-id> | Edit a note (-m message, -a append, -s severity) |
breadcrumb verify [path] | Check if notes are stale (--update to refresh hashes) |
breadcrumb search <query> | Find notes by content (-r for regex) |
breadcrumb coverage [path] | Show breadcrumb coverage stats |
breadcrumb ls | List all notes (-s filter by severity) |
breadcrumb status | Quick overview (counts) |
breadcrumb rm <path> | Remove a note (-i by ID) |
breadcrumb prune | Remove expired notes |
Staleness detection
Notes track file content hashes. When you see [STALE] prefix:
- The file has changed since the note was written
- The note may no longer be accurate
- Use judgment: the warning might still apply, or might be outdated
📝 BREADCRUMB: [STALE] Don't simplify this regex
↑ Code changed - verify note still applies
After reviewing stale notes, update hashes with:
breadcrumb verify --update
Output format
All commands output JSON. Key fields:
status: "clear", "info", or "warn"suggestion: Actionable guidance when warnings existbreadcrumbs: Array of matching breadcrumb objectsstaleness: "verified", "stale", or "unknown" (per breadcrumb)
