breadcrumb
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.
SKILL.md
Full skill instructions
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
suggestionfield
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)