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:
bash
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:
bash
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
code
📝 BREADCRUMB: [STALE] Don't simplify this regex
↑ Code changed - verify note still applies
After reviewing stale notes, update hashes with:
bash
breadcrumb verify --update
Output format
All commands output JSON. Key fields:
- •
status: "clear", "info", or "warn" - •
suggestion: Actionable guidance when warnings exist - •
breadcrumbs: Array of matching breadcrumb objects - •
staleness: "verified", "stale", or "unknown" (per breadcrumb)